gitlab-lookbook 2.3.14

data/lib/lookbook/entities/scenario_group_entity.rb

@@ -0,0 +1,135 @@
+module Lookbook
+  # Represents a group of preview scenarios within a preview class
+  #
+  # @api public
+  class ScenarioGroupEntity < Entity
+    include NavigableEntity
+
+    # @!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)
+      @preview = preview
+      @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|
+        merged.merge!(scenario.display_options)
+      end
+      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
+
+    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
+
+    # @!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
+      :scenario_group
+    end
+
+    # @!endgroup
+
+    # @api private
+    def search_terms
+      [parent.search_terms, parent.label, label]
+    end
+
+    # @api private
+    def add_scenario(scenario)
+      @scenarios.add(scenario)
+    end
+  end
+end

data/lib/lookbook/file_watcher.rb

@@ -0,0 +1,25 @@
+module Lookbook
+  class FileWatcher
+    class << self
+      def new(...)
+        file_watcher.new(...)
+      end
+
+      def evented?
+        !(file_watcher <= ActiveSupport::FileUpdateChecker)
+      end
+
+      protected
+
+      def file_watcher
+        @_file_watcher ||= begin
+          require_relative "support/evented_file_update_checker"
+
+          EventedFileUpdateChecker
+        rescue LoadError
+          ActiveSupport::FileUpdateChecker
+        end
+      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,43 @@
+module Lookbook
+  # Helpers for documentation page templates
+  #
+  # @api public
+  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?
+        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/preview_helper.rb

@@ -0,0 +1,14 @@
+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
+    end
+
+    def lookbook_data(key, fallback = nil)
+      Lookbook.data.fetch(key.to_sym, fallback)
+    end
+  end
+end

data/lib/lookbook/helpers/ui_elements_helper.rb

@@ -0,0 +1,91 @@
+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
+
+    # @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/lang.rb

@@ -0,0 +1,24 @@
+module Lookbook
+  module Lang
+    class << self
+      CONFIG_FILE = "config/languages.yml"
+      LANGUAGES = [] # retained for backwards compatability
+
+      def find(name)
+        languages.find { |l| l[:name] == name.to_s }
+      end
+
+      def guess(path, fallback_name = nil)
+        ext = File.extname(path)
+        lang = languages.find { |l| l[:ext] == ext }
+        lang || (find(fallback_name) if fallback_name)
+      end
+
+      protected
+
+      def languages
+        @_languages ||= [*ConfigLoader.call(CONFIG_FILE).definitions, *LANGUAGES]
+      end
+    end
+  end
+end

data/lib/lookbook/param.rb

@@ -0,0 +1,105 @@
+module Lookbook
+  class Param
+    attr_reader :name, :options, :value_default, :description
+
+    def initialize(name:, input: nil, description: nil, value_type: nil, value_default: nil, value: nil, options: {})
+      @name = name
+      @input = input
+      @description = description
+      @value_type = value_type
+      @value_default = value_default
+      @value = value
+      @options = options
+    end
+
+    def label
+      options.label || name.titleize
+    end
+
+    def hint
+      options.hint
+    end
+
+    def input
+      @input || guess_input
+    end
+
+    def value
+      val = @value || value_default
+      if value_type == "datetime"
+        formatter = (input == "datetime-local") ? "%Y-%m-%dT%T" : "%Y-%m-%d"
+        StringValueCaster.call(val, "datetime")&.strftime(formatter)
+      else
+        val
+      end
+    end
+
+    def value_type
+      @value_type || guess_value_type
+    end
+
+    def input_options
+      return @_input_options if @_input_options
+
+      runtime_options = options.except([*methods, :name, :value_default, :description])
+      @_input_options ||= Store.new(input_config.options.merge(runtime_options))
+    end
+
+    def input_partial
+      input_config.partial
+    end
+
+    def cast_value
+      raise ArgumentError.new("Cannot cast param '#{name}' without a value set") if value.nil?
+
+      StringValueCaster.call(value, value_type)
+    end
+
+    def self.from_tag(tag, value: nil)
+      new(
+        name: tag.name,
+        input: tag.input || tag.options.input,
+        description: tag.description || tag.options.description,
+        value_type: tag.value_type || tag.options.value_type,
+        value_default: tag.value_default,
+        options: tag.options,
+        value: value
+      )
+    end
+
+    protected
+
+    def input_config
+      config = Lookbook::Engine.inputs.get_input(input)
+      config || raise(Lookbook::Error.new("Unknown input type '#{input}'"))
+    end
+
+    def guess_input
+      if @value_type == "boolean" || (@value_type.blank? && boolean?(value_default))
+        "toggle"
+      else
+        "text"
+      end
+    end
+
+    def guess_value_type
+      if input == "toggle"
+        "boolean"
+      elsif input == "number"
+        "integer"
+      elsif boolean?(value_default)
+        "boolean"
+      elsif value_default.is_a?(Symbol)
+        "symbol"
+      elsif ["date", "datetime-local"].include?(input) || value_default.is_a?(DateTime)
+        "datetime"
+      else
+        "string"
+      end
+    end
+
+    def boolean?(value)
+      value == true || value == false
+    end
+  end
+end

data/lib/lookbook/preview.rb

@@ -0,0 +1,85 @@
+module Lookbook
+  class Preview
+    include ActionView::Helpers::TagHelper
+    include ActionView::Helpers::AssetTagHelper
+    extend PreviewAfterRender
+
+    def render(component = nil, **args, &block)
+      if component.nil?
+        {
+          type: :view,
+          template: args[:template] || Lookbook.config.preview_template,
+          args: args,
+          locals: args[:locals] || {},
+          assigns: args[:assigns] || {},
+          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
+      def preview_name
+        name.chomp("Preview").underscore
+      end
+
+      # 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_after_render.rb

@@ -0,0 +1,13 @@
+module Lookbook
+  # Shared module that both Lookbook::Preview and ViewComponent::Preview are extended with
+  module PreviewAfterRender
+    def after_render(method:, html:, context:)
+      instance = new
+      if instance.method(method).arity > 1
+        instance.send(method, html, context)
+      else
+        instance.send(method, html)
+      end.html_safe
+    end
+  end
+end

data/lib/lookbook/preview_controller_actions.rb

@@ -0,0 +1,69 @@
+module Lookbook
+  module PreviewControllerActions
+    extend ActiveSupport::Concern
+
+    included do
+      helper PreviewHelper
+      send(:helper, Rails.application.routes.url_helpers) # YARD parsing workaround: https://github.com/lsegal/yard/issues/546
+      prepend_view_path Engine.root.join("app/views")
+
+      def render_scenario_to_string(preview, scenario)
+        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 = if Lookbook.config.preview_single_pass_rendering && !scenario.group.present?
+          determine_layout(preview.layout)
+        else
+          {layout: nil}
+        end
+
+        opts[:assigns] = @render_args[:assigns] || {}
+        opts[:locals] = locals if locals.present?
+
+        with_action_view_settings do
+          rendered = render_to_string(template, **opts)
+
+          if scenario.after_render_method.present?
+            render_context = Store.new({
+              preview: preview,
+              scenario: scenario,
+              params: user_request_parameters
+            })
+            rendered = @preview.after_render(method: scenario.after_render_method, html: rendered, context: render_context)
+          end
+          render html: rendered
+        end
+      end
+
+      def render_in_layout_to_string(template, locals, opts = {})
+        with_action_view_settings 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_action_view_settings(&block)
+        ActionViewConfigHandler.call(
+          disable_annotations: Lookbook.config.preview_disable_action_view_annotations,
+          disable_partial_prefixes: Lookbook.config.preview_disable_action_view_partial_prefixes,
+          &block
+        )
+      end
+
+      def user_request_parameters
+        request.query_parameters.to_h.filter { |k, v| !k.start_with?("_") }
+      end
+    end
+  end
+end

data/lib/lookbook/preview_parser.rb

@@ -0,0 +1,53 @@
+require "yard"
+
+module Lookbook
+  class PreviewParser
+    def initialize(paths, tags = nil)
+      @paths = paths
+      @after_parse_callbacks = []
+      @after_parse_once_callbacks = []
+      @parsing = Monitor.new
+
+      define_tags(tags)
+      YARD::Parser::SourceParser.after_parse_list { run_callbacks }
+    end
+
+    def parse(files = nil, &block)
+      @parsing.synchronize do
+        @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(files_list)
+      end
+    end
+
+    def after_parse(&block)
+      @after_parse_callbacks << block
+    end
+
+    def paths
+      PathUtils.normalize_paths(@paths).map { |path| "#{path}/**/*preview.rb" }
+    end
+
+    protected
+
+    def callbacks
+      [
+        *@after_parse_callbacks,
+        *@after_parse_once_callbacks
+      ]
+    end
+
+    def run_callbacks
+      callbacks.each { |cb| cb.call(YARD::Registry) }
+      @after_parse_once_callbacks = []
+    end
+
+    def define_tags(tags = nil)
+      tags.to_h.each do |name, tag|
+        YARD::Tags::Library.define_tag(tag[:label], name, Lookbook::TagProvider)
+      end
+    end
+  end
+end