lookbook 2.0.0.beta.3 → 2.0.0.beta.4

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/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.3"
+  VERSION = "2.0.0.beta.4"
 end