primer_view_components 0.0.40 → 0.0.45

data/app/lib/primer/tabbed_component_helper.rb

@@ -20,10 +20,10 @@ module Primer
       with_panel ? :div : :nav
     end
 
-    def wrapper
+    def wrapper(**system_arguments)
       return yield unless @with_panel
 
-      render Primer::TabContainerComponent.new do
+      render Primer::TabContainerComponent.new(**system_arguments) do
         yield
       end
     end

data/app/lib/primer/view_helper.rb

@@ -8,7 +8,8 @@ module Primer
     HELPERS = {
       octicon: "Primer::OcticonComponent",
       heading: "Primer::HeadingComponent",
-      time_ago: "Primer::TimeAgoComponent"
+      time_ago: "Primer::TimeAgoComponent",
+      image: "Primer::Image"
     }.freeze
 
     HELPERS.each do |name, component|

data/lib/primer/view_components/engine.rb

@@ -13,7 +13,9 @@ module Primer
       ]
 
       config.primer_view_components = ActiveSupport::OrderedOptions.new
+
       config.primer_view_components.force_functional_colors = true
+      config.primer_view_components.force_system_arguments = false
       config.primer_view_components.silence_deprecations = false
 
       initializer "primer_view_components.assets" do |app|

data/lib/primer/view_components/linters.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+Dir[File.join(__dir__, "linters", "*.rb")].sort.each { |file| require file }

data/lib/primer/view_components/linters/argument_mappers/button.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "conversion_error"
+require_relative "system_arguments"
+
+module ERBLint
+  module Linters
+    module ArgumentMappers
+      # Maps classes in a button element to arguments for the Button component.
+      class Button
+        SCHEME_MAPPINGS = {
+          "btn-primary" => ":primary",
+          "btn-danger" => ":danger",
+          "btn-outline" => ":outline",
+          "btn-invisible" => ":invisible",
+          "btn-link" => ":link"
+        }.freeze
+
+        VARIANT_MAPPINGS = {
+          "btn-sm" => ":small",
+          "btn-large" => ":large"
+        }.freeze
+
+        TYPE_OPTIONS = %w[button reset submit].freeze
+
+        def initialize(tag)
+          @tag = tag
+        end
+
+        def to_s
+          to_args.map { |k, v| "#{k}: #{v}" }.join(", ")
+        end
+
+        def to_args
+          args = {}
+
+          args[:tag] = ":#{@tag.name}" unless @tag.name == "button"
+
+          @tag.attributes.each do |attribute|
+            attr_name = attribute.name
+
+            if attr_name == "class"
+              args = args.merge(classes_to_args(attribute))
+            elsif attr_name == "disabled"
+              args[:disabled] = true
+            elsif attr_name == "type"
+              # button is the default type, so we don't need to do anything.
+              next if attribute.value == "button"
+
+              raise ConversionError, "Button component does not support type \"#{attribute.value}\"" unless TYPE_OPTIONS.include?(attribute.value)
+
+              args[:type] = ":#{attribute.value}"
+            else
+              # Assume the attribute is a system argument.
+              args.merge!(SystemArguments.new(attribute).to_args)
+            end
+          end
+
+          args
+        end
+
+        def classes_to_args(classes)
+          classes.value.split(" ").each_with_object({}) do |class_name, acc|
+            next if class_name == "btn"
+
+            if SCHEME_MAPPINGS[class_name] && acc[:scheme].nil?
+              acc[:scheme] = SCHEME_MAPPINGS[class_name]
+            elsif VARIANT_MAPPINGS[class_name] && acc[:variant].nil?
+              acc[:variant] = VARIANT_MAPPINGS[class_name]
+            elsif class_name == "btn-block"
+              acc[:block] = true
+            elsif class_name == "BtnGroup-item"
+              acc[:group_item] = true
+            else
+              raise ConversionError, "Cannot convert class \"#{class_name}\""
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/primer/view_components/linters/argument_mappers/conversion_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module ERBLint
+  module Linters
+    module ArgumentMappers
+      # Error when converting arguments.
+      class ConversionError < StandardError; end
+    end
+  end
+end

data/lib/primer/view_components/linters/argument_mappers/system_arguments.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "conversion_error"
+
+module ERBLint
+  module Linters
+    module ArgumentMappers
+      # Maps element attributes to system arguments.
+      class SystemArguments
+        STRING_PARAMETERS = %w[aria- data-].freeze
+        TEST_SELECTOR_REGEX = /test_selector\((?<selector>.+)\)$/.freeze
+
+        attr_reader :attribute
+        def initialize(attribute)
+          @attribute = attribute
+        end
+
+        def to_args
+          if attribute.erb?
+            _, _, code_node = *attribute.node
+
+            raise ConversionError, "Cannot convert erb block" if code_node.nil?
+
+            code = code_node.loc.source.strip
+            m = code.match(TEST_SELECTOR_REGEX)
+
+            raise ConversionError, "Cannot convert erb block" if m.blank?
+
+            { test_selector: m[:selector].tr("'", '"') }
+          elsif attr_name == "data-test-selector"
+            { test_selector: attribute.value.to_json }
+          elsif attr_name.start_with?(*STRING_PARAMETERS)
+            raise ConversionError, "Cannot convert attribute \"#{attr_name}\" because its value contains an erb block" if attribute.value_node&.children&.any? { |n| n.try(:type) == :erb }
+
+            # if attribute has no value_node, it means it is a boolean attribute.
+            { "\"#{attr_name}\"" => attribute.value_node ? attribute.value.to_json : true }
+          else
+            raise ConversionError, "Cannot convert attribute \"#{attr_name}\""
+          end
+        end
+
+        def attr_name
+          attribute.name
+        end
+      end
+    end
+  end
+end

data/lib/primer/view_components/linters/button_component_migration_counter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+require_relative "argument_mappers/button"
+
+module ERBLint
+  module Linters
+    # Counts the number of times a HTML button is used instead of the component.
+    class ButtonComponentMigrationCounter < Linter
+      include Helpers
+
+      TAGS = %w[button summary a].freeze
+      CLASSES = %w[btn btn-link].freeze
+      MESSAGE = "We are migrating buttons to use [Primer::ButtonComponent](https://primer.style/view-components/components/button), please try to use that instead of raw HTML."
+
+      private
+
+      def map_arguments(tag)
+        ArgumentMappers::Button.new(tag).to_s
+      rescue ArgumentMappers::ConversionError
+        nil
+      end
+
+      def correction(args)
+        return nil if args.nil?
+
+        correction = "<%= render Primer::ButtonComponent.new"
+        correction += "(#{args})" if args.present?
+        "#{correction} do %>"
+      end
+
+      def message(args)
+        return MESSAGE if args.nil?
+
+        "#{MESSAGE}\n\nTry using:\n\n#{correction(args)}\n\nInstead of:\n"
+      end
+    end
+  end
+end

data/lib/primer/view_components/linters/flash_component_migration_counter.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module ERBLint
+  module Linters
+    # Counts the number of times a HTML flash is used instead of the component.
+    class FlashComponentMigrationCounter < Linter
+      include Helpers
+
+      TAGS = %w[div].freeze
+      CLASSES = %w[flash].freeze
+      MESSAGE = "We are migrating flashes to use [Primer::FlashComponent](https://primer.style/view-components/components/flash), please try to use that instead of raw HTML."
+    end
+  end
+end

data/lib/primer/view_components/linters/helpers.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module ERBLint
+  module Linters
+    # Helper methods for linting ERB.
+    module Helpers
+      # from https://github.com/Shopify/erb-lint/blob/6179ee2d9d681a6ec4dd02351a1e30eefa748d3d/lib/erb_lint/linters/self_closing_tag.rb
+      SELF_CLOSING_TAGS = %w[
+        area base br col command embed hr input keygen
+        link menuitem meta param source track wbr img
+      ].freeze
+
+      def self.included(base)
+        base.include(ERBLint::LinterRegistry)
+
+        define_method "run" do |processed_source|
+          @offenses_not_corrected = 0
+          tags = tags(processed_source)
+          tag_tree = build_tag_tree(tags)
+
+          tags.each do |tag|
+            next if tag.closing?
+            next unless self.class::TAGS&.include?(tag.name)
+
+            classes = tag.attributes["class"]&.value&.split(" ") || []
+
+            tag_tree[tag][:offense] = false
+
+            next unless self.class::CLASSES.blank? || (classes & self.class::CLASSES).any?
+
+            args = map_arguments(tag)
+            correction = correction(args)
+
+            tag_tree[tag][:offense] = true
+            tag_tree[tag][:correctable] = !correction.nil?
+            tag_tree[tag][:message] = message(args)
+            tag_tree[tag][:correction] = correction
+          end
+
+          tag_tree.each do |tag, h|
+            next unless h[:offense]
+
+            # We always fix the offenses using blocks. The closing tag corresponds to `<% end %>`.
+            if h[:correctable]
+              add_offense(tag.loc, h[:message], h[:correction])
+              add_offense(h[:closing].loc, h[:message], "<% end %>")
+            else
+              @offenses_not_corrected += 1
+              generate_offense(self.class, processed_source, tag, h[:message])
+            end
+          end
+
+          counter_correct?(processed_source)
+        end
+
+        define_method "autocorrect" do |processed_source, offense|
+          return unless offense.context
+
+          lambda do |corrector|
+            if offense.context.include?(counter_disable)
+              correct_counter(corrector, processed_source, offense)
+            else
+              corrector.replace(offense.source_range, offense.context)
+            end
+          end
+        end
+      end
+
+      private
+
+      # Override this function to convert the HTML element attributes to argument for a component.
+      #
+      # @return [Hash] if possible to map all attributes to arguments.
+      # @return [Nil] if cannot map to arguments.
+      def map_arguments(_tag)
+        nil
+      end
+
+      # Override this function to define how to autocorrect an element to a component.
+      #
+      # @return [String] with the text to replace the HTML element if possible to correct.
+      # @return [Nil] if cannot correct element.
+      def correction(_tag)
+        nil
+      end
+
+      # Override this function to customize the linter message.
+      #
+      # @return [String] message to show on linter error.
+      def message(_tag)
+        self.class::MESSAGE
+      end
+
+      def counter_disable
+        "erblint:counter #{self.class.name.demodulize}"
+      end
+
+      def correct_counter(corrector, processed_source, offense)
+        if processed_source.file_content.include?(counter_disable)
+          # update the counter if exists
+          corrector.replace(offense.source_range, offense.context)
+        else
+          # add comment with counter if none
+          corrector.insert_before(processed_source.source_buffer.source_range, "#{offense.context}\n")
+        end
+      end
+
+      # This assumes that the AST provided represents valid HTML, where each tag has a corresponding closing tag.
+      # From the tags, we build a structured tree which represents the tag hierarchy.
+      # With this, we are able to know where the tags start and end.
+      def build_tag_tree(tags)
+        tag_tree = {}
+        current_opened_tag = nil
+
+        tags.each do |tag|
+          if tag.closing?
+            if current_opened_tag && tag.name == current_opened_tag.name
+              tag_tree[current_opened_tag][:closing] = tag
+              current_opened_tag = tag_tree[current_opened_tag][:parent]
+            end
+
+            next
+          end
+
+          self_closing = self_closing?(tag)
+
+          tag_tree[tag] = {
+            closing: self_closing ? tag : nil,
+            parent: current_opened_tag
+          }
+
+          current_opened_tag = tag unless self_closing
+        end
+
+        tag_tree
+      end
+
+      def self_closing?(tag)
+        tag.self_closing? || SELF_CLOSING_TAGS.include?(tag.name)
+      end
+
+      def tags(processed_source)
+        processed_source.parser.nodes_with_type(:tag).map { |tag_node| BetterHtml::Tree::Tag.from_node(tag_node) }
+      end
+
+      def counter_correct?(processed_source)
+        comment_node = nil
+        expected_count = 0
+        rule_name = self.class.name.match(/:?:?(\w+)\Z/)[1]
+
+        processed_source.parser.ast.descendants(:erb).each do |node|
+          indicator_node, _, code_node, = *node
+          indicator = indicator_node&.loc&.source
+          comment = code_node&.loc&.source&.strip
+
+          if indicator == "#" && comment.start_with?("erblint:count") && comment.match(rule_name)
+            comment_node = node
+            expected_count = comment.match(/\s(\d+)\s?$/)[1].to_i
+          end
+        end
+
+        if @offenses_not_corrected.zero?
+          # have to adjust to get `\n` so we delete the whole line
+          add_offense(processed_source.to_source_range(comment_node.loc.adjust(end_pos: 1)), "Unused erblint:count comment for #{rule_name}", "") if comment_node
+          return
+        end
+
+        first_offense = @offenses[0]
+
+        if comment_node.nil?
+          add_offense(processed_source.to_source_range(first_offense.source_range), "#{rule_name}: If you must, add <%# erblint:counter #{rule_name} #{@offenses_not_corrected} %> to bypass this check.", "<%# erblint:counter #{rule_name} #{@offenses_not_corrected} %>")
+        elsif expected_count != @offenses_not_corrected
+          add_offense(processed_source.to_source_range(comment_node.loc), "Incorrect erblint:counter number for #{rule_name}. Expected: #{expected_count}, actual: #{@offenses_not_corrected}.", "<%# erblint:counter #{rule_name} #{@offenses_not_corrected} %>")
+        # the only offenses remaining are not autocorrectable, so we can ignore them
+        elsif expected_count == @offenses_not_corrected && @offenses.size == @offenses_not_corrected
+          clear_offenses
+        end
+      end
+
+      def generate_offense(klass, processed_source, tag, message = nil, replacement = nil)
+        message ||= klass::MESSAGE
+        klass_name = klass.name.demodulize
+        offense = ["#{klass_name}:#{message}", tag.node.loc.source].join("\n")
+        add_offense(processed_source.to_source_range(tag.loc), offense, replacement)
+      end
+    end
+  end
+end

data/lib/primer/view_components/version.rb

@@ -5,7 +5,7 @@ module Primer
     module VERSION
       MAJOR = 0
       MINOR = 0
-      PATCH = 40
+      PATCH = 45
 
       STRING = [MAJOR, MINOR, PATCH].join(".")
     end

data/lib/tasks/docs.rake

@@ -20,33 +20,15 @@ namespace :docs do
   end
 
   task :build do
-    require File.expand_path("./../../demo/config/environment.rb", __dir__)
-    require "primer/view_components"
-    require "yard/docs_helper"
-    require "view_component/test_helpers"
-    include ViewComponent::TestHelpers
-    include Primer::ViewHelper
-    include YARD::DocsHelper
-
-    Dir["./app/components/primer/**/*.rb"].sort.each { |file| require file }
-
-    YARD::Rake::YardocTask.new
-
-    # Custom tags for yard
-    YARD::Tags::Library.define_tag("Accessibility", :accessibility)
-    YARD::Tags::Library.define_tag("Deprecation", :deprecation)
-
-    puts "Building YARD documentation."
-    Rake::Task["yard"].execute
+    registry = generate_yard_registry
 
     puts "Converting YARD documentation to Markdown files."
 
     # Rails controller for rendering arbitrary ERB
     view_context = ApplicationController.new.tap { |c| c.request = ActionDispatch::TestRequest.create }.view_context
-
-    registry = YARD::RegistryStore.new
-    registry.load!(".yardoc")
     components = [
+      Primer::Image,
+      Primer::LocalTime,
       Primer::OcticonSymbolsComponent,
       Primer::ImageCrop,
       Primer::IconButton,
@@ -61,12 +43,12 @@ namespace :docs do
       Primer::BreadcrumbComponent,
       Primer::ButtonComponent,
       Primer::ButtonGroup,
-      Primer::ButtonMarketingComponent,
+      Primer::Alpha::ButtonMarketing,
       Primer::ClipboardCopy,
       Primer::CloseButton,
       Primer::CounterComponent,
       Primer::DetailsComponent,
-      Primer::DropdownComponent,
+      Primer::Dropdown,
       Primer::DropdownMenuComponent,
       Primer::FlashComponent,
       Primer::FlexComponent,
@@ -87,15 +69,17 @@ namespace :docs do
       Primer::SubheadComponent,
       Primer::TabContainerComponent,
       Primer::TabNavComponent,
-      Primer::TextComponent,
+      Primer::Beta::Text,
       Primer::TimeAgoComponent,
       Primer::TimelineItemComponent,
-      Primer::TooltipComponent,
+      Primer::Tooltip,
       Primer::Truncate,
       Primer::UnderlineNavComponent
     ]
 
     js_components = [
+      Primer::Dropdown,
+      Primer::LocalTime,
       Primer::ImageCrop,
       Primer::AutoComplete,
       Primer::ClipboardCopy,
@@ -108,10 +92,11 @@ namespace :docs do
     all_components = Primer::Component.descendants - [Primer::BaseComponent]
     components_needing_docs = all_components - components
 
-    components_without_examples = []
     args_for_components = []
     classes_found_in_examples = []
 
+    errors = []
+
     components.each do |component|
       documentation = registry.get(component.name)
 
@@ -130,6 +115,8 @@ namespace :docs do
         f.puts
         f.puts("import Example from '../../src/@primer/gatsby-theme-doctocat/components/example'")
 
+        initialize_method = documentation.meths.find(&:constructor?)
+
         if js_components.include?(component)
           f.puts("import RequiresJSFlash from '../../src/@primer/gatsby-theme-doctocat/components/requires-js-flash'")
           f.puts
@@ -141,97 +128,68 @@ namespace :docs do
         f.puts
         f.puts(view_context.render(inline: documentation.base_docstring))
 
-        if documentation.tags(:accessibility).any?
+        if documentation.tags(:deprecated).any?
           f.puts
-          f.puts("## Accessibility")
-          documentation.tags(:accessibility).each do |tag|
+          f.puts("## Deprecation")
+          documentation.tags(:deprecated).each do |tag|
             f.puts
             f.puts view_context.render(inline: tag.text)
           end
         end
 
-        if documentation.tags(:deprecated).any?
+        if documentation.tags(:accessibility).any?
           f.puts
-          f.puts("## Deprecation")
-          documentation.tags(:deprecated).each do |tag|
+          f.puts("## Accessibility")
+          documentation.tags(:accessibility).each do |tag|
             f.puts
             f.puts view_context.render(inline: tag.text)
           end
         end
 
-        initialize_method = documentation.meths.find(&:constructor?)
+        params = initialize_method.tags(:param)
 
-        if initialize_method.tags(:example).any?
-          f.puts
-          f.puts("## Examples")
-        else
-          components_without_examples << component
-        end
+        errors << { component.name => { arguments: "No argument documentation found" } } unless params.any?
 
-        initialize_method.tags(:example).each do |tag|
-          (name, description) = tag.name.split("|")
-          f.puts
-          f.puts("### #{name}")
-          if description
-            f.puts
-            f.puts(description)
-          end
-          f.puts
-          html = view_context.render(inline: tag.text)
-          html.scan(/class="([^"]*)"/) do |classnames|
-            classes_found_in_examples.concat(classnames[0].split(" ").reject { |c| c.starts_with?("octicon", "js", "my-") }.map { ".#{_1}"})
+        f.puts
+        f.puts("## Arguments")
+        f.puts
+        f.puts("| Name | Type | Default | Description |")
+        f.puts("| :- | :- | :- | :- |")
+
+        docummented_params = params.map(&:name)
+        component_params = component.instance_method(:initialize).parameters.map { |p| p.last.to_s }
+
+        if (docummented_params & component_params).size != component_params.size
+          err = { arguments: {} }
+          (component_params - docummented_params).each do |arg|
+            err[:arguments][arg] = "Not documented"
           end
-          f.puts("<Example src=\"#{html.tr('"', "\'").delete("\n")}\" />")
-          f.puts
-          f.puts("```erb")
-          f.puts(tag.text.to_s)
-          f.puts("```")
+
+          errors << { component.name => err }
         end
 
-        params = initialize_method.tags(:param)
-        if params.any?
-          f.puts
-          f.puts("## Arguments")
-          f.puts
-          f.puts("| Name | Type | Default | Description |")
-          f.puts("| :- | :- | :- | :- |")
-
-          args = []
-          params.each do |tag|
-            params = tag.object.parameters.find { |param| [tag.name.to_s, tag.name.to_s + ":"].include?(param[0]) }
-
-            default =
-              if params && params[1]
-                constant_name = "#{component.name}::#{params[1]}"
-                constant_value = constant_name.safe_constantize
-                if constant_value.nil?
-                  pretty_value(params[1])
-                else
-                  pretty_value(constant_value)
-                end
-              else
-                "N/A"
-              end
-
-            args << {
-              "name" => tag.name,
-              "type" => tag.types.join(", "),
-              "default" => default,
-              "description" => view_context.render(inline: tag.text)
-            }
-
-            f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{default} | #{view_context.render(inline: tag.text)} |")
-          end
+        args = []
+        params.each do |tag|
+          default_value = pretty_default_value(tag, component)
 
-          component_args = {
-            "component" => short_name,
-            "source" => "https://github.com/primer/view_components/tree/main/app/components/primer/#{component.to_s.demodulize.underscore}.rb",
-            "parameters" => args
+          args << {
+            "name" => tag.name,
+            "type" => tag.types.join(", "),
+            "default" => default_value,
+            "description" => view_context.render(inline: tag.text)
           }
 
-          args_for_components << component_args
+          f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{default_value} | #{view_context.render(inline: tag.text)} |")
         end
 
+        component_args = {
+          "component" => short_name,
+          "source" => "https://github.com/primer/view_components/tree/main/app/components/primer/#{component.to_s.demodulize.underscore}.rb",
+          "parameters" => args
+        }
+
+        args_for_components << component_args
+
         # Slots V2 docs
         slot_v2_methods = documentation.meths.select { |x| x[:renders_one] || x[:renders_many] }
 
@@ -256,22 +214,61 @@ namespace :docs do
             end
 
             param_tags.each do |tag|
-              params = tag.object.parameters.find { |param| [tag.name.to_s, tag.name.to_s + ":"].include?(param[0]) }
+              f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{pretty_default_value(tag, component)} | #{view_context.render(inline: tag.text)} |")
+            end
+          end
+        end
 
-              default =
-                if params && params[1]
-                  "`#{params[1]}`"
-                else
-                  "N/A"
-                end
+        errors << { component.name => { example: "No examples found" } } unless initialize_method.tags(:example).any?
 
-              f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{default} | #{view_context.render(inline: tag.text)} |")
-            end
+        f.puts
+        f.puts("## Examples")
+
+        initialize_method.tags(:example).each do |tag|
+          name = tag.name
+          description = nil
+          code = nil
+
+          if tag.text.include?("@description")
+            splitted = tag.text.split(/@description|@code/)
+            description = splitted.second.gsub(/^[ \t]{2}/, "").strip
+            code = splitted.last.gsub(/^[ \t]{2}/, "").strip
+          else
+            code = tag.text
+          end
+
+          f.puts
+          f.puts("### #{name}")
+          if description
+            f.puts
+            f.puts(description)
+          end
+          f.puts
+          html = view_context.render(inline: code)
+          html.scan(/class="([^"]*)"/) do |classnames|
+            classes_found_in_examples.concat(classnames[0].split(" ").reject { |c| c.starts_with?("octicon", "js", "my-") }.map { ".#{_1}"})
           end
+          f.puts("<Example src=\"#{html.tr('"', "\'").delete("\n")}\" />")
+          f.puts
+          f.puts("```erb")
+          f.puts(code.to_s)
+          f.puts("```")
         end
       end
     end
 
+    unless errors.empty?
+      puts "==============================================="
+      puts "===================== ERRORS =================="
+      puts "===============================================\n\n"
+      puts JSON.pretty_generate(errors)
+      puts "\n\n==============================================="
+      puts "==============================================="
+      puts "==============================================="
+
+      raise
+    end
+
     File.open("static/classes.yml", "w") do |f|
       f.puts YAML.dump(classes_found_in_examples.sort.uniq)
     end
@@ -299,14 +296,92 @@ namespace :docs do
 
     puts "Markdown compiled."
 
-    if components_without_examples.any?
-      puts
-      puts "The following components have no examples defined: #{components_without_examples.map(&:name).join(', ')}. Consider adding an example?"
-    end
-
     if components_needing_docs.any?
       puts
       puts "The following components needs docs. Care to contribute them? #{components_needing_docs.map(&:name).join(', ')}"
     end
   end
+
+  task :preview do
+    registry = generate_yard_registry
+
+    FileUtils.rm_rf("demo/test/components/previews/primer/docs/")
+
+    components = Primer::Component.descendants
+
+    # Generate previews from documentation examples
+    components.each do |component|
+      documentation = registry.get(component.name)
+      short_name = component.name.gsub(/Primer|::/, "")
+      initialize_method = documentation.meths.find(&:constructor?)
+
+      next unless initialize_method.tags(:example).any?
+
+      yard_example_tags = initialize_method.tags(:example)
+
+      path = Pathname.new("demo/test/components/previews/primer/docs/#{short_name.underscore}_preview.rb")
+      path.dirname.mkdir unless path.dirname.exist?
+
+      File.open(path, "w") do |f|
+        f.puts("module Primer")
+        f.puts("  module Docs")
+        f.puts("    class #{short_name}Preview < ViewComponent::Preview")
+
+        yard_example_tags.each_with_index do |tag, index|
+          method_name = tag.name.split("|").first.downcase.parameterize.underscore
+          f.puts("      def #{method_name}; end")
+          f.puts unless index == yard_example_tags.size - 1
+          path = Pathname.new("demo/test/components/previews/primer/docs/#{short_name.underscore}_preview/#{method_name}.html.erb")
+          path.dirname.mkdir unless path.dirname.exist?
+          File.open(path, "w") do |view_file|
+            view_file.puts(tag.text.to_s)
+          end
+        end
+
+        f.puts("    end")
+        f.puts("  end")
+        f.puts("end")
+      end
+    end
+  end
+
+  def generate_yard_registry
+    require File.expand_path("./../../demo/config/environment.rb", __dir__)
+    require "primer/view_components"
+    require "yard/docs_helper"
+    require "view_component/test_helpers"
+    include ViewComponent::TestHelpers
+    include Primer::ViewHelper
+    include YARD::DocsHelper
+
+    Dir["./app/components/primer/**/*.rb"].sort.each { |file| require file }
+
+    YARD::Rake::YardocTask.new
+
+    # Custom tags for yard
+    YARD::Tags::Library.define_tag("Accessibility", :accessibility)
+    YARD::Tags::Library.define_tag("Deprecation", :deprecation)
+    YARD::Tags::Library.define_tag("Parameter", :param, :with_types_name_and_default)
+
+    puts "Building YARD documentation."
+    Rake::Task["yard"].execute
+
+    registry = YARD::RegistryStore.new
+    registry.load!(".yardoc")
+    registry
+  end
+
+  def pretty_default_value(tag, component)
+    params = tag.object.parameters.find { |param| [tag.name.to_s, tag.name.to_s + ":"].include?(param[0]) }
+    default = tag.defaults&.first || params&.second
+
+    return "N/A" unless default
+
+    constant_name = "#{component.name}::#{default}"
+    constant_value = default.safe_constantize || constant_name.safe_constantize
+
+    return pretty_value(default) if constant_value.nil?
+
+    pretty_value(constant_value)
+  end
 end