primer_view_components 0.0.44 → 0.0.48

data/lib/primer/view_components.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "primer/classify"
 require "primer/view_components/version"
 require "primer/view_components/engine"
 

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

@@ -7,7 +7,7 @@ module ERBLint
     module ArgumentMappers
       # Maps element attributes to system arguments.
       class SystemArguments
-        STRING_PARAETERS = %w[aria- data-].freeze
+        STRING_PARAMETERS = %w[aria- data-].freeze
         TEST_SELECTOR_REGEX = /test_selector\((?<selector>.+)\)$/.freeze
 
         attr_reader :attribute
@@ -29,9 +29,10 @@ module ERBLint
             { test_selector: m[:selector].tr("'", '"') }
           elsif attr_name == "data-test-selector"
             { test_selector: attribute.value.to_json }
-          elsif attr_name.start_with?(*STRING_PARAETERS)
-            # if attribute has no value_node, it means it is a boolean attribute.
-            { "\"#{attr_name}\"" => attribute.value_node ? attribute.value.to_json : true }
+          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 }
+
+            { "\"#{attr_name}\"" => attribute.value.to_json }
           else
             raise ConversionError, "Cannot convert attribute \"#{attr_name}\""
           end

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

@@ -21,14 +21,18 @@ module ERBLint
         nil
       end
 
-      def message(tag)
-        args = map_arguments(tag)
+      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?
 
-        msg = "#{MESSAGE}\n\nTry using:\n\n<%= render Primer::ButtonComponent.new"
-        msg += "(#{args})" if args.present?
-        "#{msg} %>\n\nInstead of:\n"
+        "#{MESSAGE}\n\nTry using:\n\n#{correction(args)}\n\nInstead of:\n"
       end
     end
   end

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

@@ -7,34 +7,69 @@ 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
+
+      DUMP_FILE = ".erblint-counter-ignore.json"
+
       def self.included(base)
         base.include(ERBLint::LinterRegistry)
 
         define_method "run" do |processed_source|
-          tags(processed_source).each do |tag|
+          @total_offenses = 0
+          @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(" ")
+            classes = tag.attributes["class"]&.value&.split(" ") || []
 
-            next if self.class::CLASSES.any? && (classes & self.class::CLASSES).blank?
+            tag_tree[tag][:offense] = false
 
-            generate_offense(self.class, processed_source, tag, message(tag))
+            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]
+
+            @total_offenses += 1
+            # 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)
+
+          dump_data(processed_source) if ENV["DUMP_LINT_DATA"] == "1"
         end
 
         define_method "autocorrect" do |processed_source, offense|
           return unless offense.context
 
           lambda do |corrector|
-            if processed_source.file_content.include?("erblint:counter #{self.class.name.demodulize}")
-              # update the counter if exists
-              corrector.replace(offense.source_range, offense.context)
+            if offense.context.include?(counter_disable)
+              correct_counter(corrector, processed_source, offense)
             else
-              # add comment with counter if none
-              corrector.insert_before(processed_source.source_buffer.source_range, "#{offense.context}\n")
+              corrector.replace(offense.source_range, offense.context)
             end
           end
         end
@@ -42,10 +77,77 @@ module ERBLint
 
       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
@@ -54,7 +156,6 @@ module ERBLint
         comment_node = nil
         expected_count = 0
         rule_name = self.class.name.match(/:?:?(\w+)\Z/)[1]
-        offenses_count = @offenses.length
 
         processed_source.parser.ast.descendants(:erb).each do |node|
           indicator_node, _, code_node, = *node
@@ -62,32 +163,46 @@ module ERBLint
           comment = code_node&.loc&.source&.strip
 
           if indicator == "#" && comment.start_with?("erblint:count") && comment.match(rule_name)
-            comment_node = code_node
+            comment_node = node
             expected_count = comment.match(/\s(\d+)\s?$/)[1].to_i
           end
         end
 
-        if offenses_count.zero?
-          add_offense(processed_source.to_source_range(comment_node.loc), "Unused erblint:count comment for #{rule_name}") if comment_node
+        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_count} %> to bypass this check.", "<%# erblint:counter #{rule_name} #{offenses_count} %>")
-        else
+          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
-          add_offense(processed_source.to_source_range(comment_node.loc), "Incorrect erblint:counter number for #{rule_name}. Expected: #{expected_count}, actual: #{offenses_count}.", " erblint:counter #{rule_name} #{offenses_count} ") if expected_count != offenses_count
         end
       end
 
       def generate_offense(klass, processed_source, tag, message = nil, replacement = nil)
         message ||= klass::MESSAGE
-        klass_name = klass.name.split("::")[-1]
+        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
+
+      def dump_data(processed_source)
+        return if @total_offenses.zero?
+
+        data = File.exist?(DUMP_FILE) ? JSON.parse(File.read(DUMP_FILE)) : {}
+
+        data[processed_source.filename] ||= {}
+        data[processed_source.filename][self.class.name.demodulize] = @total_offenses
+
+        File.write(DUMP_FILE, JSON.pretty_generate(data))
+      end
     end
   end
 end

data/lib/primer/view_components/statuses.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Primer
+  # :nodoc:
+  module ViewComponents
+    STATUSES = JSON.parse(
+      File.read(
+        File.join(File.dirname(__FILE__), "../../../static/statuses.json")
+      )
+    ).freeze
+  end
+end

data/lib/primer/view_components/version.rb

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

data/lib/rubocop/config/default.yml

@@ -0,0 +1,12 @@
+require:
+  - rubocop/cop/primer
+
+AllCops:
+  DisabledByDefault: true
+
+Primer/SystemArgumentInsteadOfClass:
+  Enabled: true
+
+Primer/NoTagMemoize:
+  Enabled: false
+

data/lib/rubocop/cop/primer.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "rubocop/cop/primer/no_tag_memoize"
+require "rubocop/cop/primer/system_argument_instead_of_class"

data/lib/rubocop/cop/primer/no_tag_memoize.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Cop
+    module Primer
+      # This cop ensures that tags are not set with ||=
+      #
+      # bad
+      # @system_arguments[:tag] ||= :h1
+      #
+      # good
+      # @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
+      #
+      # good
+      # @system_arguments[:tag] = :h2
+      class NoTagMemoize < RuboCop::Cop::Cop
+        INVALID_MESSAGE = <<~STR
+          Avoid `[:tag] ||=`. Instead, try one of the following:
+            - Don't allow consumers to update the tag by having a fixed tag (e.g. `system_arguments[:tag] = :div`)
+            - Use the `fetch_or_fallback` helper to only allow a tag from a restricted list.
+        STR
+
+        def_node_search :tag_memoized?, <<~PATTERN
+          (or-asgn
+            (send
+              _
+              _
+              (sym :tag)
+            )
+            _
+          )
+        PATTERN
+
+        def on_or_asgn(node)
+          add_offense(node, message: INVALID_MESSAGE) if tag_memoized?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/primer/system_argument_instead_of_class.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "rubocop"
+require "primer/classify/utilities"
+require "primer/view_components/statuses"
+
+module RuboCop
+  module Cop
+    module Primer
+      # This cop ensures that components use System Arguments instead of CSS classes.
+      #
+      # bad
+      # Component.new(classes: "mr-1")
+      #
+      # good
+      # Component.new(mr: 1)
+      class SystemArgumentInsteadOfClass < RuboCop::Cop::Cop
+        INVALID_MESSAGE = <<~STR
+          Avoid using CSS classes when you can use System Arguments: https://primer.style/view-components/system-arguments.
+        STR
+
+        def on_send(node)
+          return unless node.method_name == :new
+          return unless ::Primer::ViewComponents::STATUSES.key?(node.receiver.const_name)
+          return unless node.arguments?
+
+          # we are looking for hash arguments and they are always last
+          kwargs = node.arguments.last
+
+          return unless kwargs.type == :hash
+
+          # find classes pair
+          classes_arg = kwargs.pairs.find { |kwarg| kwarg.key.value == :classes }
+
+          return if classes_arg.nil?
+          return unless classes_arg.value.type == :str
+
+          # get actual classes
+          classes = classes_arg.value.value
+
+          system_arguments = ::Primer::Classify::Utilities.classes_to_hash(classes)
+
+          # no classes are fixable
+          return if system_arguments[:classes] == classes
+
+          add_offense(classes_arg, message: INVALID_MESSAGE)
+        end
+
+        def autocorrect(node)
+          lambda do |corrector|
+            system_arguments = ::Primer::Classify::Utilities.classes_to_hash(node.value.value)
+            corrector.replace(node.loc.expression, arguments_as_string(system_arguments))
+          end
+        end
+
+        private
+
+        def arguments_as_string(system_arguments)
+          system_arguments.map do |key, value|
+            val = case value
+                  when Symbol
+                    ":#{value}"
+                  when String
+                    value.to_json
+                  else
+                    value
+                  end
+
+            "#{key}: #{val}"
+          end.join(", ")
+        end
+      end
+    end
+  end
+end

data/lib/tasks/docs.rake

@@ -32,9 +32,9 @@ namespace :docs do
       Primer::OcticonSymbolsComponent,
       Primer::ImageCrop,
       Primer::IconButton,
-      Primer::AutoComplete,
-      Primer::AutoComplete::Item,
-      Primer::AvatarComponent,
+      Primer::Beta::AutoComplete,
+      Primer::Beta::AutoComplete::Item,
+      Primer::Beta::Avatar,
       Primer::AvatarStackComponent,
       Primer::BaseButton,
       Primer::BlankslateComponent,
@@ -81,7 +81,7 @@ namespace :docs do
       Primer::Dropdown,
       Primer::LocalTime,
       Primer::ImageCrop,
-      Primer::AutoComplete,
+      Primer::Beta::AutoComplete,
       Primer::ClipboardCopy,
       Primer::TabContainerComponent,
       Primer::TabNavComponent,
@@ -97,28 +97,30 @@ namespace :docs do
 
     errors = []
 
-    components.each do |component|
+    # Deletes docs before regenerating them, guaranteeing that we don't keep stale docs.
+    FileUtils.rm_rf(Dir.glob("docs/content/components/**/*.md"))
+
+    components.sort_by(&:name).each do |component|
       documentation = registry.get(component.name)
 
-      # Primer::AvatarComponent => Avatar
-      short_name = component.name.gsub(/Primer|::|Component/, "")
+      data = docs_metadata(component)
 
-      path = Pathname.new("docs/content/components/#{short_name.downcase}.md")
+      path = Pathname.new(data[:path])
       path.dirname.mkdir unless path.dirname.exist?
       File.open(path, "w") do |f|
         f.puts("---")
-        f.puts("title: #{short_name}")
-        f.puts("status: #{component.status.to_s.capitalize}")
-        f.puts("source: https://github.com/primer/view_components/tree/main/app/components/primer/#{component.to_s.demodulize.underscore}.rb")
-        f.puts("storybook: https://primer.style/view-components/stories/?path=/story/primer-#{short_name.underscore.dasherize}-component")
+        f.puts("title: #{data[:title]}")
+        f.puts("status: #{data[:status]}")
+        f.puts("source: #{data[:source]}")
+        f.puts("storybook: #{data[:storybook]}")
         f.puts("---")
         f.puts
-        f.puts("import Example from '../../src/@primer/gatsby-theme-doctocat/components/example'")
+        f.puts("import Example from '#{data[:example_path]}'")
 
         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("import RequiresJSFlash from '#{data[:require_js_path]}'")
           f.puts
           f.puts("<RequiresJSFlash />")
         end
@@ -176,15 +178,15 @@ namespace :docs do
             "name" => tag.name,
             "type" => tag.types.join(", "),
             "default" => default_value,
-            "description" => view_context.render(inline: tag.text)
+            "description" => view_context.render(inline: tag.text.squish)
           }
 
-          f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{default_value} | #{view_context.render(inline: tag.text)} |")
+          f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{default_value} | #{view_context.render(inline: tag.text.squish)} |")
         end
 
         component_args = {
-          "component" => short_name,
-          "source" => "https://github.com/primer/view_components/tree/main/app/components/primer/#{component.to_s.demodulize.underscore}.rb",
+          "component" => data[:title],
+          "source" => data[:source],
           "parameters" => args
         }
 
@@ -346,6 +348,7 @@ namespace :docs do
   end
 
   def generate_yard_registry
+    ENV["SKIP_STORYBOOK_PRELOAD"] = "1"
     require File.expand_path("./../../demo/config/environment.rb", __dir__)
     require "primer/view_components"
     require "yard/docs_helper"
@@ -384,4 +387,55 @@ namespace :docs do
 
     pretty_value(constant_value)
   end
+
+  def status_module_and_short_name(component)
+    name_with_status = component.name.gsub(/Primer::|Component/, "")
+
+    m = name_with_status.match(/(?<status>Beta|Alpha|Deprecated)?(::)?(?<name>.*)/)
+    [m[:status]&.downcase, m[:name].gsub("::", "")]
+  end
+
+  def docs_metadata(component)
+    (status_module, short_name) = status_module_and_short_name(component)
+    status_path = status_module.nil? ? "" : "#{status_module}/"
+    status = component.status.to_s
+
+    {
+      title: short_name,
+      status: status.capitalize,
+      source: source_url(component),
+      storybook: storybook_url(component),
+      path: "docs/content/components/#{status_path}#{short_name.downcase}.md",
+      example_path: example_path(component),
+      require_js_path: require_js_path(component)
+    }
+  end
+
+  def source_url(component)
+    path = component.name.split("::").map(&:underscore).join("/")
+
+    "https://github.com/primer/view_components/tree/main/app/components/#{path}.rb"
+  end
+
+  def storybook_url(component)
+    path = component.name.split("::").map { |n| n.underscore.dasherize }.join("-")
+
+    "https://primer.style/view-components/stories/?path=/story/#{path}"
+  end
+
+  def example_path(component)
+    example_path = "../../src/@primer/gatsby-theme-doctocat/components/example"
+    example_path = "../#{example_path}" if status_module?(component)
+    example_path
+  end
+
+  def require_js_path(component)
+    require_js_path = "../../src/@primer/gatsby-theme-doctocat/components/requires-js-flash"
+    require_js_path = "../#{require_js_path}" if status_module?(component)
+    require_js_path
+  end
+
+  def status_module?(component)
+    (%w[Alpha Beta] & component.name.split("::")).any?
+  end
 end