gitlab-lookbook 2.3.14

data/lib/lookbook/entities/page_section_entity.rb

@@ -0,0 +1,47 @@
+module Lookbook
+  # Represents a documentation page section.
+  #
+  # @ignore methods
+  # @api private
+  class PageSectionEntity < PageEntity
+    attr_accessor :parent
+
+    def initialize(file_path)
+      @file_path = Pathname(file_path)
+      @parent = nil
+      super
+    end
+
+    def name
+      Utils.name(name_parts[:name])
+    end
+
+    def lookup_path
+      directory = if relative_directory_path.present? && !relative_directory_path.to_s.start_with?(".")
+        relative_directory_path
+      end
+
+      path = PathUtils.to_path(directory, name_parts[:parent_name])
+      PathUtils.to_lookup_path(path)
+    end
+
+    def landing?
+      false
+    end
+
+    def url_path
+      nil
+    end
+
+    alias_method :page, :parent
+
+    protected
+
+    def name_parts
+      return @_name_parts if @_name_parts
+
+      matches = file_name(true).match(/(?<parent_name>.*)\[(?<name>.*)\]/)
+      @_name_parts ||= {name: matches[:name], parent_name: matches[:parent_name]}
+    end
+  end
+end

data/lib/lookbook/entities/preview_entity.rb

@@ -0,0 +1,214 @@
+module Lookbook
+  # Represents a preview class
+  #
+  # @api public
+  class PreviewEntity < Entity
+    include AnnotatableEntity
+    include LocatableEntity
+    include NavigableEntity
+
+    delegate :after_render, :render_args, to: :preview_class
+
+    # @api private
+    attr_reader :preview_class
+
+    # @api private
+    def initialize(code_object)
+      @code_object = code_object
+      @preview_class = code_object.path.constantize
+      @file_path = Pathname(code_object.file)
+      @base_directories = Engine.preview_paths
+
+      cleaned_path = preview_class.name.underscore.strip
+        .gsub(/(_component_preview|_preview)(\..+)?$/, "")
+        .gsub(/\/(component_preview|preview|component)(\..+)?$/, "")
+
+      @lookup_path = PathUtils.to_lookup_path(cleaned_path)
+    end
+
+    # @!group Scenarios
+
+    # Get all scenarios defined in the preview class.
+    #
+    # @example :ruby
+    #   scenario_names = preview.scenarios.map(&:name)
+    #
+    # @return [Array<ScenarioEntity>] All scenarios for the preview
+    def scenarios
+      @_scenarios ||= ScenarioCollection.new(load_scenarios)
+    end
+
+    alias_method :examples, :scenarios
+    deprecate examples: :scenarios, deprecator: Deprecation
+
+    # Find a specific scenario by (i.e. method) name
+    #
+    # @example :ruby
+    #   default_scenario_preview_path = preview.scenario(:default).preview_path
+    #
+    # @param scenario_name [Symbol, String] Name of the scenario
+    # @return [ScenarioEntity] The matching scenario, if found
+    # @return [nil] if no matching scenario was found
+    def scenario(scenario_name)
+      scenarios.find { |m| m.name == scenario_name.to_s }
+    end
+
+    alias_method :example, :scenario
+    deprecate example: :scenario, deprecator: Deprecation
+
+    # Get all scenarios defined in the preview class that
+    # have not been hidden (by using the `@hidden` tag).
+    #
+    # @example :ruby
+    #   visible_scenario_names = preview.visible_scenarios.map(&:name)
+    #
+    # @return [Array<ScenarioEntity>] All visible scenarios for the preview
+    def visible_scenarios
+      @_visible_scenarios ||= ScenarioCollection.new(scenarios.select(&:visible?))
+    end
+
+    # Get all scenarios defined in the preview class
+    # that are hidden (using the `@hidden` tag) and so
+    # will not show up in the navigation.
+    #
+    # @example :ruby
+    #   hidden_scenario_names = preview.hidden_scenarios.map(&:name)
+    #
+    # @return [Array<ScenarioEntity>] All hidden scenarios for the preview
+    def hidden_scenarios
+      @_hidden_scenarios ||= ScenarioCollection.new(scenarios.select(&:hidden?))
+    end
+
+    # The scenario used when a preview is rendered
+    # without explicity specifying a scenario.
+    #
+    # @example :ruby
+    #   default_scenario_name = preview.default_scenario.name
+    #
+    # @return [ScenarioEntity] The default scenario for this preview
+    def default_scenario
+      visible_scenarios.first
+    end
+
+    # @!endgroup
+
+    # @!group Render Targets
+
+    # All 'render targets' (i.e. components or partials) that are known
+    # to be rendered within the scenarios defined within this preview.
+    #
+    # Render targets are guessed where possible (based on the preview class name)
+    # but can also be manually specified using the `@renders` tag.
+    #
+    # @example :ruby
+    #  "This preview renders: #{preview.render_targets.map(&:label).join(", ")}"
+    #
+    # @return [Array<RenderableEntity>] All known render targets used in the preview
+    def render_targets
+      @_render_targets ||= RenderTargetCollection.new(scenarios.flat_map(&:render_targets).uniq(&:lookup_path))
+    end
+
+    alias_method :components, :render_targets
+
+    # @api private
+    def render_target
+      render_targets.first
+    end
+
+    # @api private
+    alias_method :component, :render_target
+
+    # @!endgroup
+
+    # @!group URLs
+
+    # The inspector URL path for this preview
+    #
+    # @return [String] URL path
+    def inspect_path
+      lookbook_inspect_path(lookup_path)
+    end
+
+    alias_method :url_path, :inspect_path
+
+    # The standalone preview URL path for this preview
+    #
+    # @return [String] URL path
+    def preview_path
+      lookbook_preview_path(lookup_path)
+    end
+
+    # @!endgroup
+
+    # The name of the associated preview class
+    #
+    # @return [String] Class name
+    def preview_class_name
+      preview_class.name
+    end
+
+    # @api private
+    def file_name_base
+      @_file_name_slug ||= file_name(true).gsub(/(_component_preview|component_preview|_preview|preview|component)$/, "")
+    end
+
+    # @api private
+    def display_options
+      global_options = Lookbook.config.preview_display_options
+      global_options.deep_merge(fetch_config(:display_options, {}))
+    end
+
+    # @api private
+    def after_render_method
+      fetch_config(:after_render)
+    end
+
+    # @api private
+    def layout
+      preview_class.instance_variable_get(:@layout)
+    end
+
+    # @api private
+    def guess_render_targets
+      [preview_class.name.chomp("Preview").constantize&.name]
+    rescue
+      []
+    end
+
+    protected
+
+    def load_scenarios
+      code_object.groups.any? ? grouped_scenario_entities : scenario_entities
+    end
+
+    def grouped_scenario_entities
+      scenarios = []
+      scenario_entities.each.with_index(1) do |entity, i|
+        if entity.group.nil?
+          entity.default_priority = i
+          scenarios << entity
+        else
+          group_name = entity.group.presence || entity.parent.name.pluralize
+          group = scenarios.find do |s|
+            s.is_a?(ScenarioGroupEntity) && s.name == Utils.name(group_name)
+          end
+
+          if group
+            group.add_scenario(entity)
+          else
+            group = ScenarioGroupEntity.new(group_name, [entity], self)
+            group.default_priority = i
+            scenarios << group
+          end
+        end
+      end
+      scenarios
+    end
+
+    def scenario_entities
+      public_methods = preview_class.public_instance_methods(false)
+      method_objects = code_object.meths.select { |m| public_methods.include?(m.name) }
+      method_objects.map.with_index { |code_object, i| ScenarioEntity.new(code_object, self, priority: i) }
+    end
+  end
+end

data/lib/lookbook/entities/renderable_entity.rb

@@ -0,0 +1,101 @@
+module Lookbook
+  # Represents the component or view template partial
+  # that is being rendered in a preview.
+  #
+  # @api public
+  class RenderableEntity < Entity
+    include LocatableEntity
+
+    # @api private
+    def initialize(identifier)
+      @identifier = identifier
+      @base_directories = Engine.component_paths
+
+      @file_path = if component?
+        PathUtils.determine_full_path("#{name}.rb", @base_directories).presence || begin
+          locations = Where.is_class(identifier.constantize)
+          dirs = @base_directories.sort_by { |d| d.size * -1 }
+          lookup = locations.find do |loc|
+            dirs.find { |d| loc[0].start_with?(d) }
+          end
+          lookup[0] if lookup
+        end
+      else
+        PathUtils.determine_full_path(identifier, @base_directories)
+      end
+
+      unless @file_path && File.exist?(@file_path)
+        raise Lookbook::Error, "The render target #{@identifier} was not found."
+      end
+      @lookup_path = PathUtils.to_lookup_path(relative_file_path)
+    end
+
+    # @!group Identity
+
+    # Parameter-safe entity name.
+    #
+    # @return [String]
+    def name
+      component? ? component_class.name.underscore : @identifier
+    end
+
+    # Entity type identifier.
+    # Returns `:component` for components and
+    # `:template` for view templates/partials.
+    #
+    # @return [Symbol] The entity type
+    def type
+      component? ? :component : :template
+    end
+
+    # @!endgroup
+
+    # @!group Components
+
+    # The associated component class (if the renderable is a component).
+    #
+    # @return [Class] The component class
+    def component_class
+      @identifier.constantize if component?
+    end
+
+    # Whether or not the renderable is a component without a template.
+    #
+    # @return [Boolean] True if no template is present
+    def inline?
+      component? ? template_file_path.present? : false
+    end
+
+    # Whether or not the renderable is a component
+    # (as opposed to a view template/partial).
+    #
+    # @return [Boolean] True if component
+    def component?
+      @identifier.first.upcase == @identifier.first &&
+        !@identifier.include?(".") &&
+        !@identifier.include?("/")
+    end
+
+    # Whether or not the renderable is a view template/partial
+    # (as opposed to a component).
+    #
+    # @return [Boolean] True if component
+    def template?
+      !component?
+    end
+
+    # @!endgroup
+
+    # @!group Paths
+
+    # Full path to the component template (if present)
+    # or view template/partial.
+    #
+    # @return [Class] The component class
+    def template_file_path
+      component? ? Dir.glob("#{directory_path}/#{file_name(true)}.*.erb").first : file_path
+    end
+
+    # @!endgroup
+  end
+end

data/lib/lookbook/entities/rendered_scenario_entity.rb

@@ -0,0 +1,69 @@
+module Lookbook
+  # Represents a **rendered** preview scenario.
+  #
+  # Extends ScenarioEntity with an `output`
+  # method that returns the rendered HTML output.
+  #
+  # See the [ScenarioEntity](./scenario_entity) docs for other available methods.
+  #
+  # @api public
+  class RenderedScenarioEntity
+    delegate_missing_to :scenario
+
+    # @api private
+    attr_reader :scenario
+
+    # @api private
+    def initialize(scenario, output, params)
+      @scenario = scenario
+      @params = params
+      @output = output
+    end
+
+    # HTML output of the rendered scenario.
+    #
+    # @return [String] Rendered output
+    attr_reader :output
+
+    # 'Beautified' HTML output of the rendered scenario.
+    #
+    # @return [String] Rendered output
+    def beautified_output
+      @_beautified_output ||= CodeBeautifier.call(output)
+    end
+
+    # @api private
+    def source
+      has_custom_template? ? template_source(template) : scenario.source
+    end
+
+    # @api private
+    def source_lang
+      has_custom_template? ? template_lang(template) : scenario.source_lang
+    end
+
+    protected
+
+    attr_reader :params
+
+    def render_args
+      @_render_args ||= preview.render_args(scenario.name, params: params)
+    end
+
+    def template
+      render_args[:template]
+    end
+
+    def view?
+      render_args[:type] == :view
+    end
+
+    def has_custom_template?
+      !template.in?(system_templates) && !custom_source? && !view?
+    end
+
+    def system_templates
+      ["view_components/preview", Lookbook.config.preview_template]
+    end
+  end
+end

data/lib/lookbook/entities/scenario_entity.rb

@@ -0,0 +1,182 @@
+module Lookbook
+  # Represents a preview scenario method within a preview class
+  #
+  # @api public
+  class ScenarioEntity < Entity
+    include InspectableEntity
+    include AnnotatableEntity
+    include NavigableEntity
+
+    delegate :group, to: :code_object
+
+    # The preview that this scenario belongs to.
+    #
+    # @return [PreviewEntity] The parent preview entity
+    attr_reader :preview
+
+    # @api private
+    alias_method :parent, :preview
+
+    # @api private
+    def initialize(code_object, preview, priority: nil)
+      @code_object = code_object
+      @preview = preview
+      @default_priority = priority
+      @lookup_path = "#{parent.lookup_path}/#{name}"
+    end
+
+    # @!group Identity
+
+    # Human-readable unique scenario ID
+    #
+    # @return [String] The ID
+    def id
+      @_id ||= Utils.id(fetch_config(:id) { "#{parent.id}-#{code_object.name}" })
+    end
+
+    # Parameter-safe scenario name.
+    #
+    # @return [String] The name
+    def name
+      @_name ||= Utils.name(code_object.name)
+    end
+
+    # Entity type identifier.
+    # Returns `:scenario` for scenarios.
+    #
+    # @return [Symbol] The entity type
+    def type
+      :scenario
+    end
+
+    # @!endgroup
+
+    # @!group Display options
+
+    # Display options hash.
+    #
+    # Contains all display options defined via the `@display` tag
+    # merged with any globally-defined options.
+    #
+    # @return [Hash] The resolved display options
+    def display_options
+      parent.display_options.merge(fetch_config(:display_options, {}))
+    end
+
+    # @!endgroup
+
+    # @!group Render Targets
+
+    # @api private
+    def render_targets
+      @_render_targets ||= RenderTargetCollection.new(load_render_targets)
+    end
+
+    # @api private
+    alias_method :components, :render_targets
+
+    # The item (component or partial) that the scenario renders.
+    #
+    # The render target is guessed where possible (based on the preview class name)
+    # but can also be manually specified using the `@renders` tag.
+    #
+    # @example :ruby
+    #  "This scenario renders: #{scenario.render_target.label}"
+    #
+    # @return [RenderableEntity] The render target
+    def render_target
+      render_targets.first
+    end
+
+    alias_method :component, :render_target
+
+    # @!endgroup
+
+    # @!group URLs
+
+    # The inspector URL path for this preview
+    #
+    # @return [String] URL path
+    def inspect_path
+      lookbook_inspect_path(lookup_path)
+    end
+
+    # The standalone preview URL path for this preview
+    #
+    # @return [String] URL path
+    def preview_path
+      lookbook_preview_path(lookup_path)
+    end
+
+    # @!endgroup
+
+    # @api private
+    def after_render_method
+      fetch_config(:after_render) || parent.after_render_method
+    end
+
+    # @api private
+    def scenarios
+      [self]
+    end
+
+    # @api private
+    def template_source(template_path)
+      source_path = template_file_path(template_path)
+      source_path ? File.read(source_path) : nil
+    end
+
+    # @api private
+    def template_lang(template_path)
+      path = template_file_path(template_path)
+      Lookbook::Lang.guess(path) || Lookbook::Lang.find(:html)
+    end
+
+    # @api private
+    def search_terms
+      [parent.search_terms, parent.label, label]
+    end
+
+    alias_method :lang, :source_lang
+    alias_method :examples, :scenarios
+    alias_method :url_path, :inspect_path
+
+    deprecate lang: :source_lang, deprecator: Deprecation
+    deprecate examples: :scenarios, deprecator: Deprecation
+
+    protected
+
+    def sort_handler(other_entity)
+      if Lookbook.config.preview_sort_scenarios
+        label <=> other_entity.label
+      else
+        [priority, label] <=> [other_entity.priority, other_entity.label]
+      end
+    end
+
+    def format_source(source)
+      source.sub(/^def \w+\s?(\([^)]+\))?/m, "").split("\n")[0..-2].join("\n")
+    end
+
+    def template_file_path(template_path)
+      return full_template_path(template_path) if respond_to?(:full_template_path, true)
+
+      search_dirs = [*Engine.preview_paths, *Engine.view_paths]
+      template_path = "#{template_path.to_s.sub(/\..*$/, "")}.html.*"
+      PathUtils.determine_full_path(template_path, search_dirs)
+    end
+
+    def load_render_targets
+      render_target_identifiers = [*fetch_config(:renders, []), *preview.send(:fetch_config, :renders, [])]
+      render_target_identifiers = preview.guess_render_targets if render_target_identifiers.empty?
+
+      render_targets = render_target_identifiers.map do |render_target|
+        RenderableEntity.new(render_target)
+      rescue Lookbook::Error, NameError
+        Lookbook.logger.warn "#{render_target} was not found"
+        nil
+      end
+      render_targets.compact.uniq(&:lookup_path)
+    end
+  end
+end