lookbook 1.5.0 → 2.0.0.beta.0

data/lib/lookbook/entities/scenario_entity.rb

@@ -0,0 +1,112 @@
+module Lookbook
+  # Represents a preview scenario method within a preview class
+  #
+  # @ignore methods
+  # @api public
+  class ScenarioEntity < Entity
+    include InspectableEntity
+    include AnnotatableEntity
+    include NavigableEntity
+
+    delegate :group, to: :code_object
+
+    attr_reader :preview
+
+    def initialize(code_object, preview, priority: nil)
+      @code_object = code_object
+      @preview = preview
+      @default_priority = priority
+      @lookup_path = "#{parent.lookup_path}/#{name}"
+    end
+
+    def id
+      @_id ||= Utils.id(fetch_config(:id) { "#{parent.id}-#{code_object.name}" })
+    end
+
+    def name
+      @_name ||= Utils.name(code_object.name)
+    end
+
+    def display_options
+      parent.display_options.merge(fetch_config(:display_options, {}))
+    end
+
+    def render_targets
+      @_render_targets ||= RenderTargetCollection.new(load_render_targets)
+    end
+
+    def render_target
+      render_targets.first
+    end
+
+    def scenarios
+      [self]
+    end
+
+    def template_source(template_path)
+      source_path = template_file_path(template_path)
+      source_path ? File.read(source_path) : nil
+    end
+
+    def template_lang(template_path)
+      path = template_file_path(template_path)
+      Lookbook::Lang.guess(path) || Lookbook::Lang.find(:html)
+    end
+
+    def search_terms
+      [parent.label, label]
+    end
+
+    def url_path
+      lookbook_inspect_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
+
+    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 NameError
+        Lookbook.logger.warn "#{render_target} was not found"
+        nil
+      end
+      render_targets.compact.uniq(&:lookup_path)
+    end
+  end
+end

data/lib/lookbook/entities/scenario_group_entity.rb

@@ -0,0 +1,53 @@
+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
+
+    def initialize(name, scenarios, preview)
+      @name = Utils.name(name)
+      @scenarios = ScenarioCollection.new(scenarios)
+      @preview = preview
+      @lookup_path = "#{parent.lookup_path}/#{@name}"
+    end
+
+    def display_options
+      merged = {}
+      scenarios.to_a.reverse.map do |scenario|
+        merged.merge!(scenario.display_options)
+      end
+      merged
+    end
+
+    def render_targets
+      @_render_targets ||= RenderTargetCollection.new(scenarios.flat_map(&:render_targets).uniq(&:path))
+    end
+
+    def search_terms
+      [parent.label, label]
+    end
+
+    def tags(tag_name = nil)
+      scenarios.flat_map { |scenario| scenario.tags(tag_name) }
+    end
+
+    def tag(tag_name = nil)
+      tags(tag_name).first
+    end
+
+    def url_path
+      lookbook_inspect_path(lookup_path)
+    end
+
+    def type
+      :group
+    end
+
+    alias_method :parent, :preview
+    alias_method :components, :render_targets
+  end
+end

data/lib/lookbook/error.rb

@@ -1,6 +1,6 @@
 module Lookbook
   class Error < StandardError
-    delegate :full_message, :backtrace, :to_s, to: :target
+    delegate :full_message, :backtrace, :to_s, to: :original
 
     LINES_AROUND = 3
 
@@ -59,11 +59,11 @@ module Lookbook
     end
 
     def title
-      @title || target.class.to_s
+      @title || original.class.to_s
     end
 
     def message
-      (@message || target.message).gsub("(<unknown>):", "").strip.upcase_first
+      (@message || original.message).gsub("(<unknown>):", "").strip.upcase_first
     end
 
     def file_name
@@ -80,7 +80,7 @@ module Lookbook
       else
         @file_path.presence || nil
       end
-      path&.to_s&.delete_prefix("#{Rails.root}/")
+      path.nil? ? nil : path.to_s.delete_prefix("#{Rails.root}/")
     end
 
     def line_number
@@ -101,7 +101,7 @@ module Lookbook
 
     protected
 
-    def target
+    def original
       @original.presence || self
     end
 

data/lib/lookbook/file_watcher.rb

@@ -1,46 +1,30 @@
 module Lookbook
   class FileWatcher
-    attr_reader :listeners, :force_polling
-
-    def initialize(force_polling: false)
-      @force_polling = force_polling
-      @listeners = []
-    end
-
-    def watch(paths, extensions = ".*", opts = nil, &block)
-      paths = PathUtils.normalize_paths(paths)
-
-      if paths.any?
-        opts = opts.to_h
-        opts[:only] = /\.(#{Array(extensions).join("|")})$/
-
-        listeners << init_listener(paths, opts, &block)
+    class << self
+      def new(...)
+        if evented?
+          Lookbook.logger.debug "Using `EventedFileUpdateChecker` for file watching"
+        else
+          Lookbook.logger.debug "The 'listen' gem was not found. Using `FileUpdateChecker` for file watching"
+        end
+
+        file_watcher.new(...)
       end
-    end
 
-    def start
-      if listeners.any?
-        Lookbook.logger.debug "Starting listeners"
-        listeners.each { |l| l.start }
+      def evented?
+        !(file_watcher <= ActiveSupport::FileUpdateChecker)
       end
-    end
 
-    def stop
-      if listeners.any?
-        Lookbook.logger.debug "Stopping listeners"
-        listeners.each { |l| l.stop }
-      end
-    end
+      protected
 
-    protected
+      def file_watcher
+        @_file_watcher ||= begin
+          require_relative "./support/evented_file_update_checker"
 
-    def init_listener(paths, opts, &block)
-      Listen.to(
-        *paths,
-        **opts,
-        force_polling: force_polling
-      ) do |modified, added, removed|
-        block.call({modified: modified, added: added, removed: removed})
+          EventedFileUpdateChecker
+        rescue LoadError
+          ActiveSupport::FileUpdateChecker
+        end
       end
     end
   end

data/lib/lookbook/helpers/class_names_helper.rb

@@ -0,0 +1,28 @@
+module Lookbook
+  module ClassNamesHelper
+    def build_tag_values(*args)
+      tag_values = []
+
+      args.each do |tag_value|
+        case tag_value
+        when Hash
+          tag_value.each do |key, val|
+            tag_values << key.to_s if val && key.present?
+          end
+        when Array
+          tag_values.concat build_tag_values(*tag_value)
+        else
+          tag_values << tag_value.to_s if tag_value.present?
+        end
+      end
+
+      tag_values
+    end
+
+    def class_names(*args)
+      tokens = build_tag_values(*args).flat_map { |value| value.to_s.split(/\s+/) }.uniq
+
+      safe_join(tokens, " ")
+    end
+  end
+end

data/lib/lookbook/helpers/page_helper.rb

@@ -0,0 +1,18 @@
+module Lookbook
+  # Helpers for documentation page templates
+  #
+  # @api public
+  module PageHelper
+    # Returns the URL path to a page.
+    #
+    # @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
+      else
+        Lookbook.logger.warn "Could not find page with id ':#{id}'"
+      end
+    end
+  end
+end

data/{app/helpers/lookbook → lib/lookbook/helpers}/preview_helper.rb

@@ -1,4 +1,7 @@
 module Lookbook
+  # Set of helpers for preview layouts
+  #
+  # @api public
   module PreviewHelper
     def lookbook_display(key, fallback = nil)
       params.dig(:lookbook, :display, key.to_sym) || fallback

data/lib/lookbook/helpers/ui_elements_helper.rb

@@ -0,0 +1,115 @@
+module Lookbook
+  # Helpers for rendering UI elements.
+  #
+  # These are available for use in documentation page templates
+  # and custom preview inspector panel templates.
+  #
+  # @api public
+  module UiElementsHelper
+    # Render an icon.
+    #
+    # Lookbook uses icons from the [Lucide Icons](https://lucide.dev/) set and
+    # a full list of available icon names can be found on that site.
+    #
+    # @example
+    #   <%= icon :trash %>
+    #   <%= icon :camera, size: 6, style: "color: red;" %>
+    #
+    # @param name [Symbol, String] Name of the icon
+    # @param opts [Hash] Options hash
+    def icon(name, **opts)
+      lookbook_render :icon, name: name, **opts
+    end
+
+    # Display a syntax-highlighted block of code.
+    #
+    # An alternative to using markdown code blocks for templates that have
+    # markdown parsing disabled, or for when more control is required.
+    #
+    # @param language [Symbol] Which language the code is written in
+    # @param opts [Hash] Options hash
+    # @param block [Proc] Code block
+    def code(language = :html, **opts, &block)
+      opts[:language] ||= language
+      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
+    end
+
+    # @api private
+    def lookbook_tag(tag = :div, **attrs, &block)
+      lookbook_render :tag, tag: tag, **attrs, &block
+    end
+
+    # @api private
+    def lookbook_render(ref, **attrs, &block)
+      comp = if ref.is_a? ViewComponent::Base
+        ref
+      else
+        klass = component_class(ref)
+        attrs.key?(:content) ? klass.new(**attrs.except(:content)).with_content(attrs[:content]) : klass.new(**attrs)
+      end
+      if block && !attrs.key?(:content)
+        public_send render_method_name, comp, &block
+      else
+        public_send render_method_name, comp
+      end
+    end
+
+    private
+
+    COMPONENT_CLASSES = {} # cache for constantized references
+
+    # @api private
+    def render_method_name
+      if Rails.application.config.view_component.render_monkey_patch_enabled || Rails.version.to_f >= 6.1
+        :render
+      else
+        :render_component
+      end
+    end
+
+    # @api private
+    def component_class(ref)
+      klass = COMPONENT_CLASSES[ref]
+      if klass.nil?
+        ref = ref.to_s.tr("-", "_")
+        class_namespace = ref.camelize
+        begin
+          klass = "Lookbook::#{class_namespace}::Component".constantize
+        rescue
+          klass = "Lookbook::#{class_namespace}Component".constantize
+        end
+        COMPONENT_CLASSES[ref] = klass
+      end
+      klass
+    end
+  end
+end

data/lib/lookbook/preview.rb

@@ -0,0 +1,79 @@
+module Lookbook
+  class Preview
+    include ActionView::Helpers::TagHelper
+    include ActionView::Helpers::AssetTagHelper
+
+    def render(component = nil, **args, &block)
+      if component.nil?
+        {
+          type: :view,
+          template: args[:template] || Lookbook.config.preview_template,
+          args: args,
+          locals: args[:locals] || {},
+          block: block
+        }
+      else
+        {
+          type: component.is_a?(String) ? :view : :component,
+          args: args,
+          block: block,
+          component: component,
+          locals: {},
+          template: Lookbook.config.preview_template
+        }
+      end
+    end
+
+    def render_with_template(template: nil, locals: nil)
+      {
+        type: :template,
+        template: template,
+        locals: locals.to_h
+      }
+    end
+
+    alias_method :render_component, :render
+
+    class << self
+      # Returns the arguments for rendering of the component in its layout
+      def render_args(scenario, params: {})
+        scenario_params_names = instance_method(scenario).parameters.map(&:last)
+        provided_params = params.slice(*scenario_params_names).to_h.symbolize_keys
+        result = provided_params.empty? ? new.public_send(scenario) : new.public_send(scenario, **provided_params)
+        result ||= {}
+        result[:template] = scenario_template_path(scenario) if result[:template].nil?
+        @layout = nil unless defined?(@layout)
+        result.merge(layout: @layout)
+      end
+
+      # rubocop:disable Style/TrivialAccessors
+      def layout(layout_name)
+        @layout = layout_name
+      end
+      # rubocop:enable Style/TrivialAccessors
+
+      # Returns the relative path (from preview_path) to the scenario template if the template exists
+      def scenario_template_path(scenario)
+        preview_name = name.chomp("Preview").underscore
+        preview_path =
+          Engine.preview_paths.detect do |path|
+            Dir["#{path}/#{preview_name}_preview/#{scenario}.html.*"].first
+          end
+
+        if preview_path.nil?
+          raise(
+            PreviewTemplateError,
+            "A preview template for scenario #{scenario} doesn't exist.\n\n" \
+            "To fix this issue, create a template for the scenario."
+          )
+        end
+
+        path = Dir["#{preview_path}/#{preview_name}_preview/#{scenario}.html.*"].first
+        Pathname.new(path)
+          .relative_path_from(Pathname.new(preview_path))
+          .to_s
+          .sub(/\..*$/, "")
+      end
+    end
+  end
+end

data/lib/lookbook/preview_controller_actions.rb

@@ -0,0 +1,50 @@
+module Lookbook
+  module PreviewControllerActions
+    extend ActiveSupport::Concern
+
+    included do
+      helper PreviewHelper
+      prepend_view_path Engine.root.join("app/views")
+      before_action :permit_embeds
+
+      def render_scenario_to_string(preview, scenario_name)
+        prepend_application_view_paths
+        prepend_preview_examples_view_path
+
+        @preview = preview
+        @scenario_name = scenario_name
+        @render_args = @preview.render_args(@scenario_name, params: params.permit!)
+        template = @render_args[:template]
+        locals = @render_args[:locals]
+        opts = {}
+        opts[:layout] = nil
+        opts[:locals] = locals if locals.present?
+
+        with_optional_action_view_annotations do
+          render html: render_to_string(template, **opts)
+        end
+      end
+
+      def render_in_layout_to_string(template, locals, opts = {})
+        with_optional_action_view_annotations do
+          html = render_to_string(template, locals: locals, **determine_layout(opts[:layout]))
+          if opts[:append_html].present?
+            html += opts[:append_html]
+          end
+          render html: html
+        end
+      end
+
+      protected
+
+      def with_optional_action_view_annotations(&block)
+        disable = Lookbook.config.preview_disable_action_view_annotations
+        ActionViewAnnotationsHandler.call(disable_annotations: disable, &block)
+      end
+
+      def permit_embeds
+        headers["X-Frame-Options"] = Lookbook.config.preview_embeds.policy
+      end
+    end
+  end
+end

data/lib/lookbook/preview_parser.rb

@@ -12,12 +12,14 @@ module Lookbook
       YARD::Parser::SourceParser.after_parse_list { run_callbacks }
     end
 
-    def parse(&block)
+    def parse(files = nil, &block)
       unless @parsing
         @parsing = true
         @after_parse_once_callbacks << block if block
+        files_list = files ? files.select { |file| file.to_s.end_with?(".rb") } : paths
+
         YARD::Registry.clear
-        YARD.parse(paths)
+        YARD.parse(files_list)
       end
     end
 

data/lib/lookbook/reloaders.rb

@@ -0,0 +1,71 @@
+require "active_support"
+
+module Lookbook
+  class Reloaders
+    attr_reader :reloaders
+
+    def initialize
+      @reloaders = []
+    end
+
+    def add(name, directories, extensions, &callback)
+      reloader = Reloader.new(name, directories, extensions, &callback)
+      reloaders.push(reloader)
+
+      if Engine.reloading?
+        Rails.application.reloaders << reloader
+        Rails.application.reloader.to_run { reloader.execute_if_updated }
+      end
+    end
+
+    def execute
+      reloaders.each { |reloader| reloader.execute }
+    end
+
+    def register_changes(changes)
+      reloader = reloaders.find { |reloader| reloader.watching?(changes) }
+      reloader.last_changes = changes if reloader
+    end
+
+    class Reloader
+      delegate :execute, :execute_if_updated, :updated?, to: :file_watcher
+
+      attr_reader :name, :directories, :extensions, :callback
+      attr_accessor :last_changes
+
+      def initialize(name, directories, extensions, &callback)
+        @name = name.to_sym
+        @directories = directories
+        @extensions = extensions
+        @callback = callback
+        @last_changes = nil
+      end
+
+      def watching?(changes)
+        file_paths = changes.to_h.values.flatten
+        !!file_paths.find do |file_path|
+          file_path = Pathname(file_path).expand_path
+          directories.find do |dir_path|
+            matcher = File.expand_path(File.join(dir_path, "**"))
+            file_path.fnmatch?(matcher)
+          end
+        end
+      end
+
+      protected
+
+      def file_watcher
+        return @_file_watcher if @_file_watcher
+
+        to_watch = directories.each_with_object({}) do |directory, result|
+          result[directory] = extensions
+        end
+
+        @_file_watcher ||= FileWatcher.new([], to_watch) do
+          callback.call(@last_changes)
+          @last_changes = nil
+        end
+      end
+    end
+  end
+end