lookbook 2.0.0.beta.3 → 2.0.0.beta.5

data/lib/lookbook/entities/preview_entity.rb

@@ -1,7 +1,6 @@
 module Lookbook
   # Represents a preview class
   #
-  # @ignore methods
   # @api public
   class PreviewEntity < Entity
     include AnnotatableEntity
@@ -10,8 +9,10 @@ module Lookbook
 
     delegate :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
@@ -25,69 +26,178 @@ module Lookbook
       @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
 
-    def display_options
-      global_options = Lookbook.config.preview_display_options
-      global_options.deep_merge(fetch_config(:display_options, {}))
-    end
+    # @api private
+    alias_method :component, :render_target
 
-    def layout
-      preview_class.instance_variable_get(:@layout)
-    end
+    # @!endgroup
 
-    def url_path
+    # @!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)$/, "")
+    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 layout
+      preview_class.instance_variable_get(:@layout)
+    end
+
+    # @api private
     def guess_render_targets
       [preview_class.name.chomp("Preview").constantize&.name]
     rescue
       []
     end
 
-    alias_method :components, :render_targets
-    alias_method :component, :render_target
-    alias_method :examples, :scenarios
-    alias_method :example, :scenario
-
-    deprecate examples: :scenarios, deprecator: Deprecation
-    deprecate example: :scenario, deprecator: Deprecation
-
     protected
 
     def load_scenarios
-      return scenario_entities unless code_object.groups.any?
+      code_object.groups.any? ? grouped_scenario_entities : scenario_entities
+    end
 
-      scenario_entities.group_by(&:group).flat_map do |group_name, grouped_scenarios|
-        group_name.nil? ? grouped_scenarios : ScenarioGroupEntity.new(group_name.presence || label.pluralize, grouped_scenarios, self)
+    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

data/lib/lookbook/entities/renderable_entity.rb

@@ -2,49 +2,87 @@ module Lookbook
   # Represents the component or view template partial
   # that is being rendered in a preview.
   #
-  # @ignore methods
   # @api public
   class RenderableEntity < Entity
     include LocatableEntity
 
+    # @api private
     def initialize(identifier)
       @identifier = identifier
       @base_directories = Engine.component_paths
       @file_path = PathUtils.determine_full_path(component? ? "#{name}.rb" : identifier, @base_directories)
       unless @file_path && File.exist?(@file_path)
-        raise LookbookError, "The render target #{@identifier} was not found."
+        raise Lookbook::Error, "The render target #{@identifier} was not found."
       end
       @lookup_path = PathUtils.to_lookup_path(relative_file_path)
     end
 
-    def component_class
-      @identifier.constantize if component?
-    end
+    # @!group Identity
 
+    # Parameter-safe entity name.
+    #
+    # @return [String]
     def name
       component? ? component_class.name.underscore : @identifier
     end
 
-    def template_file_path
-      component? ? Dir.glob("#{directory_path}/#{file_name(true)}.*.erb").first : file_path
+    # 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
 
-    def type
-      component? ? :component : :template
+    # @!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

@@ -1,31 +1,42 @@
 module Lookbook
-  # Represents a **rendered** preview scenario
+  # 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.
   #
-  # @ignore 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
+    def output
+      @_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
 
-    def output
-      @_output ||= CodeBeautifier.call(@output)
-    end
-
     protected
 
     attr_reader :params

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,90 @@ 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
+
+    # @api private
+    def add_scenario(scenario)
+      @scenarios.add(scenario)
+    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