lookbook 2.0.0.beta.2 → 2.0.0.beta.4

data/lib/lookbook/entities/scenario_entity.rb

@@ -1,7 +1,6 @@
 module Lookbook
   # Represents a preview scenario method within a preview class
   #
-  # @ignore methods
   # @api public
   class ScenarioEntity < Entity
     include InspectableEntity
@@ -10,8 +9,15 @@ module Lookbook
 
     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
@@ -19,61 +25,116 @@ module Lookbook
       @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 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.label, label]
     end
 
-    def url_path
-      lookbook_inspect_path(lookup_path)
-    end
-
-    def preview_path
-      lookbook_preview_path(lookup_path)
-    end
-
-    def type
-      :scenario
-    end
-
-    alias_method :parent, :preview
-    alias_method :components, :render_targets
-    alias_method :component, :render_target
     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

data/lib/lookbook/entities/scenario_group_entity.rb

@@ -1,13 +1,28 @@
 module Lookbook
   # Represents a group of preview scenarios within a preview class
   #
-  # @ignore methods
   # @api public
   class ScenarioGroupEntity < Entity
     include NavigableEntity
 
-    attr_reader :scenarios, :preview
+    # @!group Scenarios
 
+    # Returns all scenarios within the group.
+    #
+    # @return [Array<ScenarioEntity>] All scenarios
+    attr_reader :scenarios
+
+    # @!endgroup
+
+    # 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(name, scenarios, preview)
       @name = Utils.name(name)
       @scenarios = ScenarioCollection.new(scenarios)
@@ -15,6 +30,14 @@ module Lookbook
       @lookup_path = "#{parent.lookup_path}/#{@name}"
     end
 
+    # @!group Display options
+
+    # Display options hash.
+    #
+    # Contains all display options defined via the `@display` tag
+    # for each scenario in the group, merged with any globally-defined options.
+    #
+    # @return [Hash] The resolved display options
     def display_options
       merged = {}
       scenarios.to_a.reverse.map do |scenario|
@@ -23,35 +46,85 @@ module Lookbook
       merged
     end
 
+    # @!endgroup
+
+    # @!group Render Targets
+
+    # Collection of render targets (components or partials)
+    # from each of the scenarios in the group.
+    #
+    # 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 group renders: #{group.render_targets.map(&:label).join(", ")}"
+    #
+    # @return [Array<RenderableEntity>] Render target entities
     def render_targets
       @_render_targets ||= RenderTargetCollection.new(scenarios.flat_map(&:render_targets).uniq(&:lookup_path))
     end
 
-    def search_terms
-      [parent.label, label]
-    end
+    alias_method :components, :render_targets
+
+    # @!endgroup
 
+    # @!group Annotations
+
+    # Collection of tags from each of the scenarios in the group.
+    # Can be filtered by tag name by providing the name as an argument.
+    #
+    # @example :ruby
+    #   all_tags = group.tags
+    #   display_tags = group.tags(:display)
+    #
+    # @param tag_name [Symbol] Optional tag type to filter by
+    # @return [Array<YardTag>] Array of tags
     def tags(tag_name = nil)
       scenarios.flat_map { |scenario| scenario.tags(tag_name) }
     end
 
+    # @api private
     def tag(tag_name = nil)
       tags(tag_name).first
     end
 
-    def url_path
+    # @!endgroup
+
+    # @!group URLs
+
+    # The inspector URL path for this scenario group
+    #
+    # @return [String] URL path
+    def inspect_path
       lookbook_inspect_path(lookup_path)
     end
 
+    # The standalone preview URL path for this scenario group
+    #
+    # @return [String] URL path
     def preview_path
       lookbook_preview_path(lookup_path)
     end
 
+    alias_method :url_path, :inspect_path
+
+    # @!endgroup
+
+    # @!group Identity
+
+    # Entity type identifier.
+    # Returns `:scenario_group` for scenario groups.
+    #
+    # @return [Symbol] The entity type
     def type
-      :group
+      :scenario_group
     end
 
-    alias_method :parent, :preview
-    alias_method :components, :render_targets
+    # @!endgroup
+
+    # @api private
+    def search_terms
+      [parent.label, label]
+    end
   end
 end

data/lib/lookbook/helpers/page_helper.rb

@@ -5,14 +5,39 @@ module Lookbook
   module PageHelper
     # Returns the URL path to a page.
     #
+    # @api private
     # @param id [String, PageEntity] The id or PageEntity instance to generate a URL path for
     def page_path(id)
       page = id.is_a?(PageEntity) ? id : Engine.pages.find_by_id(id)
       if page.present?
-        lookbook_page_path page.lookup_path
+        page.docs_path
       else
         Lookbook.logger.warn "Could not find page with id ':#{id}'"
       end
     end
+
+    # Render a 'live' embed of a component preview.
+    #
+    # If no scenario name is provided then the default (first) preview
+    # scenario will be rendered in the embed.
+    #
+    # @param preview [String] Name of the preview class to embed
+    # @param scenario [String] Example method name
+    # @param opts [Hash] Options hash
+    def embed(preview, scenario = nil, **opts)
+      preview_entity = if preview.is_a?(Symbol)
+        Engine.previews.find_by_path(preview)
+      else
+        Engine.previews.find_by_preview_class(preview)
+      end
+      scenario_entity = scenario ? preview_entity&.scenario(scenario) : preview_entity&.default_scenario
+      opts[:actions] ||= ["inspect", "open"]
+
+      lookbook_render Embed::Component.new(
+        scenario: scenario_entity,
+        params: opts.fetch(:params, {}),
+        options: opts.except(:params)
+      )
+    end
   end
 end

data/lib/lookbook/helpers/ui_elements_helper.rb

@@ -34,30 +34,6 @@ module Lookbook
       lookbook_render :code, **opts, &block
     end
 
-    # Render a 'live' embed of a component preview.
-    #
-    # If no scenario name is provided then the default (first) preview
-    # scenario will be rendered in the embed.
-    #
-    # @param preview [String] Name of the preview class to embed
-    # @param scenario [String] Example method name
-    # @param opts [Hash] Options hash
-    def embed(preview, scenario = nil, **opts)
-      preview_entity = if preview.is_a?(Symbol)
-        Engine.previews.find_by_path(preview)
-      else
-        Engine.previews.find_by_preview_class(preview)
-      end
-      scenario_entity = scenario ? preview_entity&.scenario(scenario) : preview_entity&.default_scenario
-      opts[:actions] ||= ["inspect", "open"]
-
-      lookbook_render Embed::Component.new(
-        scenario: scenario_entity,
-        params: opts.fetch(:params, {}),
-        options: opts.except(:params)
-      )
-    end
-
     # @api private
     def prose(**opts, &block)
       lookbook_render :prose, **opts, &block

data/lib/lookbook/param.rb

@@ -65,7 +65,7 @@ module Lookbook
 
     def input_config
       config = Lookbook::Engine.inputs.get_input(input)
-      config || raise(LookbookError.new("Unknown input type '#{input}'"))
+      config || raise(Lookbook::Error.new("Unknown input type '#{input}'"))
     end
 
     def guess_input

data/lib/lookbook/services/markdown_renderer.rb

@@ -18,11 +18,9 @@ module Lookbook
     class LookbookMarkdownRenderer < Redcarpet::Render::HTML
       def block_code(code, language = "ruby")
         line_numbers = language.to_s.end_with? "-numbered"
-        ApplicationController.render(Lookbook::Code::Component.new(**{
-          source: code,
+        ApplicationController.render(Lookbook::Code::Component.new(source: code,
           language: language.to_s.chomp("-numbered"),
-          line_numbers: line_numbers
-        }), layout: nil)
+          line_numbers: line_numbers), layout: nil)
       end
 
       def postprocess(full_document)

data/lib/lookbook/stores/config_store.rb

@@ -27,22 +27,10 @@ module Lookbook
       store[:project_name] = (name == false) ? nil : name
     end
 
-    def page_paths=(paths = nil)
-      store[:page_paths].push(*paths.to_a)
-    end
-
     def page_extensions=(extensions = nil)
       store[:page_extensions].push(*extensions.to_a).uniq!
     end
 
-    def preview_paths=(paths = nil)
-      store[:preview_paths].push(*paths.to_a)
-    end
-
-    def component_paths=(paths = nil)
-      store[:component_paths].push(*paths.to_a)
-    end
-
     def listen_extensions=(extensions = nil)
       store[:listen_extensions].push(*extensions.to_a).uniq!
     end

data/lib/lookbook/support/errors/config_error.rb

@@ -1,5 +1,5 @@
 module Lookbook
-  class ConfigError < LookbookError
+  class ConfigError < Error
     def initialize(msg = nil, scope: "config", **kwargs)
       super(msg, scope: scope, **kwargs)
     end

data/lib/lookbook/support/errors/error.rb

@@ -0,0 +1,64 @@
+module Lookbook
+  class Error < StandardError
+    attr_reader :scope, :original, :status, :detail, :source
+
+    def initialize(message = nil,
+      scope: nil, original: nil, status: nil, detail: nil,
+      file_path: nil, source: nil, line_number: nil, **kwargs)
+      @scope = scope
+      @original = original
+      @message = message
+      @status = status
+      @detail = detail
+      @file_path = file_path
+      @source = source
+      @line_number = line_number
+      super(message)
+    end
+
+    def message
+      @message || original&.message
+    end
+
+    def backtrace
+      original&.backtrace || super
+    end
+
+    def type
+      (original.presence || self).class.to_s
+    end
+
+    def file_path
+      return @file_path.to_s if @file_path.present?
+
+      parsed_backtrace[0][0] if parsed_backtrace.any?
+    end
+
+    def relative_file_path
+      file_path&.delete_prefix("#{Rails.root}/")
+    end
+
+    def line_number
+      return @line_number.to_i if @line_number.present?
+
+      if parsed_backtrace.any?
+        number = parsed_backtrace[0][1]
+        number.to_i if number.present?
+      end
+    end
+
+    def backtrace_lines
+      root = Rails.root.to_s
+      backtrace.map { |line| line.gsub(root, "") }
+    end
+
+    protected
+
+    def parsed_backtrace
+      backtrace.map do |line|
+        line =~ /^(.+?):(\d+)(|:in `(.+)')$/
+        [$1, $2, $4]
+      end
+    end
+  end
+end

data/lib/lookbook/support/errors/parser_error.rb

@@ -1,5 +1,5 @@
 module Lookbook
-  class ParserError < LookbookError
+  class ParserError < Error
     def initialize(msg = nil, scope: "parser", **kwargs)
       super(msg, scope: scope, **kwargs)
     end

data/lib/lookbook/support/errors/preview_template_error.rb

@@ -1,5 +1,5 @@
 module Lookbook
-  class PreviewTemplateError < LookbookError
+  class PreviewTemplateError < Error
     def initialize(msg = nil, scope: "preview", **kwargs)
       super(msg, scope: scope, **kwargs)
     end

data/lib/lookbook/support/errors/routing_error.rb

@@ -0,0 +1,7 @@
+module Lookbook
+  class RoutingError < Error
+    def initialize(msg = nil, scope: "request", **kwargs)
+      super(msg, scope: scope, status: :not_found, **kwargs)
+    end
+  end
+end

data/lib/lookbook/support/errors/template_error.rb

@@ -0,0 +1,7 @@
+module Lookbook
+  class TemplateError < Error
+    def initialize(msg = nil, scope: "template", **kwargs)
+      super(msg, scope: scope, **kwargs)
+    end
+  end
+end

data/lib/lookbook/version.rb

@@ -1,3 +1,3 @@
 module Lookbook
-  VERSION = "2.0.0.beta.2"
+  VERSION = "2.0.0.beta.4"
 end