primer_view_components 0.0.60 → 0.0.61

data/app/components/primer/blankslate_component.rb

@@ -6,7 +6,7 @@ module Primer
   #   `Blankslate` renders an `<h3>` element for the title by default. Update the heading level based on what is appropriate for your page hierarchy by setting `title_tag`.
   #   <%= link_to_heading_practices %>
   class BlankslateComponent < Primer::Component
-    status :beta
+    status :deprecated
 
     # Optional Spinner.
     #

data/app/components/primer/component.rb

@@ -16,8 +16,8 @@ module Primer
 
     private
 
-    def force_system_arguments?
-      Rails.application.config.primer_view_components.force_system_arguments
+    def raise_on_invalid_options?
+      Rails.application.config.primer_view_components.raise_on_invalid_options
     end
 
     def deprecated_component_warning(new_class: nil, version: nil)

data/app/components/primer/hellip_button.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Primer
+  # Use `HellipButton` to render a button with a hellip. Often used for hidden text expanders.
+  # @accessibility
+  #   Always set an accessible label to help the user interact with the component.
+  #
+  #   * This button is displaying a hellip as its content (The three dots character). Therefore a label is needed for screen readers.
+  #   * Set the attribute `aria-label` on the system arguments. E.g. `Primer::HellipButton.new("aria-label": "Expand next part")`
+  class HellipButton < Primer::Component
+    # @example Default
+    #   <%= render(Primer::HellipButton.new("aria-label": "No effect")) %>
+    #
+    # @example Inline
+    #   <%= render(Primer::HellipButton.new(inline: true, "aria-label": "No effect")) %>
+    #
+    # @example Styling the button
+    #   <%= render(Primer::HellipButton.new(p: 1, classes: "custom-class", "aria-label": "No effect")) %>
+    #
+    # @param inline [Boolean] Whether or not the button is inline.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(inline: false, **system_arguments)
+      @system_arguments = system_arguments
+
+      validate_aria_label
+
+      @system_arguments[:tag] = :button
+      @system_arguments[:"aria-expanded"] = false
+      @system_arguments[:classes] = class_names(
+        @system_arguments[:classes],
+        "inline" => inline
+      )
+    end
+
+    def call
+      render(Primer::BaseButton.new(**@system_arguments)) { "&hellip;".html_safe }
+    end
+  end
+end

data/app/components/primer/hidden_text_expander.rb

@@ -2,21 +2,29 @@
 
 module Primer
   # Use `HiddenTextExpander` to indicate and toggle hidden text.
+  #
+  # @accessibility
+  #   `HiddenTextExpander` requires an `aria-label`, which will provide assistive technologies with an accessible label.
+  #   The `aria-label` should describe the action to be invoked by the `HiddenTextExpander`. For instance,
+  #   if your `HiddenTextExpander` expands a list of 5 comments, the `aria-label` should be
+  #   `"Expand 5 more comments"` instead of `"More"`.
   class HiddenTextExpander < Primer::Component
     # @example Default
-    #   <%= render(Primer::HiddenTextExpander.new) %>
+    #   <%= render(Primer::HiddenTextExpander.new("aria-label": "No effect")) %>
     #
     # @example Inline
-    #   <%= render(Primer::HiddenTextExpander.new(inline: true)) %>
+    #   <%= render(Primer::HiddenTextExpander.new(inline: true, "aria-label": "No effect")) %>
     #
     # @example Styling the button
-    #   <%= render(Primer::HiddenTextExpander.new(button_arguments: { p: 1, classes: "custom-class" })) %>
+    #   <%= render(Primer::HiddenTextExpander.new("aria-label": "No effect", button_arguments: { p: 1, classes: "custom-class" })) %>
     #
     # @param inline [Boolean] Whether or not the expander is inline.
     # @param button_arguments [Hash] <%= link_to_system_arguments_docs %> for the button element.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(inline: false, button_arguments: {}, **system_arguments)
       @system_arguments = system_arguments
+      @button_arguments = button_arguments
+
       @system_arguments[:tag] = :span
       @system_arguments[:classes] = class_names(
         "hidden-text-expander",
@@ -24,8 +32,12 @@ module Primer
         "inline" => inline
       )
 
-      @button_arguments = button_arguments
-      @button_arguments[:"aria-expanded"] = false
+      aria_label = system_arguments[:"aria-label"] || system_arguments.dig(:aria, :label) || @aria_label
+      if aria_label.present?
+        @button_arguments[:"aria-label"] = aria_label
+        @system_arguments[:aria]&.delete(:label)
+      end
+
       @button_arguments[:classes] = class_names(
         "ellipsis-expander",
         button_arguments[:classes]
@@ -34,7 +46,7 @@ module Primer
 
     def call
       render(Primer::BaseComponent.new(**@system_arguments)) do
-        render(Primer::BaseButton.new(**@button_arguments)) { "&hellip;".html_safe }
+        render(Primer::HellipButton.new(**@button_arguments))
       end
     end
   end

data/app/components/primer/subhead_component.rb

@@ -117,7 +117,7 @@ module Primer
       @system_arguments[:classes] =
         class_names(
           @system_arguments[:classes],
-          "Subhead hx_Subhead--responsive",
+          "Subhead",
           "Subhead--spacious": spacious,
           "border-bottom-0": hide_border
         )

data/lib/primer/classify.rb

@@ -105,7 +105,7 @@ module Primer
       def validated_class_names(classes)
         return if classes.blank?
 
-        if force_system_arguments? && !ENV["PRIMER_WARNINGS_DISABLED"]
+        if raise_on_invalid_options? && !ENV["PRIMER_WARNINGS_DISABLED"]
           invalid_class_names =
             classes.split.each_with_object([]) do |class_name, memo|
               memo << class_name if Primer::Classify::Validation.invalid?(class_name)
@@ -211,8 +211,8 @@ module Primer
         end
       end
 
-      def force_system_arguments?
-        Rails.application.config.primer_view_components.force_system_arguments
+      def raise_on_invalid_options?
+        Rails.application.config.primer_view_components.raise_on_invalid_options
       end
     end
 

data/lib/primer/view_components/engine.rb

@@ -15,7 +15,7 @@ module Primer
 
       config.primer_view_components = ActiveSupport::OrderedOptions.new
 
-      config.primer_view_components.force_system_arguments = false
+      config.primer_view_components.raise_on_invalid_options = false
       config.primer_view_components.silence_deprecations = false
       config.primer_view_components.validate_class_names = !Rails.env.production?
 

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

@@ -4,6 +4,8 @@ require "json"
 require "openssl"
 require "primer/view_components/constants"
 
+require_relative "tag_tree_helpers"
+
 # :nocov:
 
 module ERBLint
@@ -14,11 +16,7 @@ module ERBLint
     # * `CLASSES` - optional - The CSS classes that the component needs. The linter will only match elements with one of those classes.
     # * `REQUIRED_ARGUMENTS` - optional - A list of HTML attributes that are required by the component.
     class BaseLinter < Linter
-      # 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
+      include TagTreeHelpers
 
       DUMP_FILE = ".erblint-counter-ignore.json"
       DISALLOWED_CLASSES = [].freeze
@@ -136,53 +134,6 @@ module ERBLint
         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(processed_source)
-        nodes = processed_source.ast.children
-        tag_tree = {}
-        tags = []
-        current_opened_tag = nil
-
-        nodes.each do |node|
-          if node.type == :tag
-            # get the tag from previously calculated list so the references are the same
-            tag = BetterHtml::Tree::Tag.from_node(node)
-            tags << 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] = {
-              tag: tag,
-              closing: self_closing ? tag : nil,
-              parent: current_opened_tag,
-              children: []
-            }
-
-            tag_tree[current_opened_tag][:children] << tag_tree[tag] if current_opened_tag
-            current_opened_tag = tag unless self_closing
-          elsif current_opened_tag
-            tag_tree[current_opened_tag][:children] << node
-          end
-        end
-
-        [tags, 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

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/indent"
+require_relative "helpers/rubocop_helpers"
+
+module ERBLint
+  module Linters
+    # Migrates from `Primer::BlankslateComponent` to `Primer::Beta::Blankslate`.
+    class BlankslateApiMigration < Linter
+      include ERBLint::LinterRegistry
+      include Helpers::RubocopHelpers
+
+      def run(processed_source)
+        processed_source.ast.descendants(:erb).each do |erb_node|
+          _, _, code_node = *erb_node
+          code = code_node.children.first.strip
+
+          next unless code.include?("Primer::BlankslateComponent")
+          # Don't fix custom blankslates
+          next if code.end_with?("do")
+
+          line = erb_node.loc.source_line
+          indent = line.split("<%=").first.size
+
+          ast = erb_ast(code)
+          kwargs = ast.arguments.first.arguments.last
+
+          replacement = build_replacement_blankslate(kwargs, indent)
+
+          add_offense(processed_source.to_source_range(erb_node.loc), "`Primer::BlankslateComponent` is deprecated. `Primer::Beta::Blankslate` should be used instead", replacement)
+        end
+      end
+
+      def autocorrect(_, offense)
+        return unless offense.context
+
+        lambda do |corrector|
+          corrector.replace(offense.source_range, offense.context)
+        end
+      end
+
+      private
+
+      def build_blankslate_arguments(kwargs)
+        new_blankslate = {
+          arguments: {},
+          slots: {
+            visual_icon: {},
+            visual_image: {},
+            heading: {
+              tag: ":h2"
+            },
+            description: {},
+            primary_action: {},
+            secondary_action: {}
+          }
+        }
+
+        kwargs&.pairs&.each do |pair|
+          source_value = pair.value.source
+
+          case pair.key.value.to_sym
+          when :title
+            new_blankslate[:slots][:heading][:content] = pair.value.value
+          when :title_tag
+            new_blankslate[:slots][:heading][:tag] = source_value
+          when :icon
+            new_blankslate[:slots][:visual_icon][:icon] = source_value
+          when :icon_size
+            new_blankslate[:slots][:visual_icon][:size] = source_value
+          when :image_src
+            new_blankslate[:slots][:visual_image][:src] = source_value
+          when :image_alt
+            new_blankslate[:slots][:visual_image][:alt] = source_value
+          when :description
+            new_blankslate[:slots][:description][:content] = pair.value.value
+          when :button_text
+            new_blankslate[:slots][:primary_action][:content] = pair.value.value
+          when :button_url
+            new_blankslate[:slots][:primary_action][:href] = source_value
+          when :button_classes
+            new_blankslate[:slots][:primary_action][:classes] = source_value
+          when :link_text
+            new_blankslate[:slots][:secondary_action][:content] = pair.value.value
+          when :link_url
+            new_blankslate[:slots][:secondary_action][:href] = source_value
+          when :large
+            next # Large does not exist anymore
+          else
+            new_blankslate[:arguments][pair.key.source] = source_value
+          end
+        end
+
+        new_blankslate
+      end
+
+      def build_replacement_blankslate(kwargs, indent)
+        data = build_blankslate_arguments(kwargs)
+        component_args = args_to_s(data[:arguments])
+
+        # If Blankslate has no heading, we don't update it.
+        return if data[:slots][:heading][:content].nil?
+        # If Blankslate sets both image and icon. don't update it.
+        return if data[:slots][:visual_icon].present? && data[:slots][:visual_image].present?
+
+        slots = data[:slots].map do |slot, slot_data|
+          next if slot_data.empty?
+
+          slot_args = args_to_s(slot_data.except(:content))
+          content = slot_data[:content]
+
+          if content
+            <<~HTML.indent(2)
+              <% c.#{slot}#{slot_args} do %>
+                #{content}
+              <% end %>
+            HTML
+          else
+            <<~HTML.indent(2)
+              <% c.#{slot}#{slot_args} %>
+            HTML
+          end
+        end.compact.join("\n").chomp
+
+        # Body needs to match the file indentation.
+        body = <<~HTML.indent(indent).chomp
+          #{slots}
+          <% end %>
+        HTML
+
+        # The render call will always be aligned.
+        "<%= render Primer::Beta::Blankslate.new#{component_args} do |c| %>\n#{body}"
+      end
+
+      def args_to_s(args)
+        string_args = args.except(:__polymorphic_type).map { |k, v| "#{k}: #{v}" }.join(", ")
+
+        string_args = ":#{args[:__polymorphic_type]}, #{string_args}" if args[:__polymorphic_type]
+
+        return string_args if string_args.blank?
+
+        "(#{string_args})"
+      end
+    end
+  end
+end

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

@@ -6,7 +6,7 @@ module ERBLint
   module Linters
     # Counts the number of times a HTML Blankslate is used instead of the component.
     class BlankslateComponentMigrationCounter < BaseLinter
-      MESSAGE = "We are migrating Blankslate to use [Primer::BlankslateComponent](https://primer.style/view-components/components/blankslate), please try to use that instead of raw HTML."
+      MESSAGE = "We are migrating Blankslate to use [Primer::Beta::Blankslate](https://primer.style/view-components/components/beta/blankslate), please try to use that instead of raw HTML."
       CLASSES = %w[blankslate].freeze
       TAGS = %w[div].freeze
     end

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

@@ -3,12 +3,14 @@
 require_relative "base_linter"
 require_relative "autocorrectable"
 require_relative "argument_mappers/close_button"
+require_relative "helpers/rubocop_helpers"
 
 module ERBLint
   module Linters
     # Counts the number of times a HTML clipboard-copy is used instead of the component.
     class CloseButtonComponentMigrationCounter < BaseLinter
       include Autocorrectable
+      include Helpers::RubocopHelpers
 
       TAGS = %w[button].freeze
       CLASSES = %w[close-button].freeze
@@ -109,10 +111,6 @@ module ERBLint
         (kwargs.keys.map { |key| key.value.to_s } - ALLOWED_OCTICON_ARGS).present?
       end
 
-      def erb_ast(code)
-        RuboCop::AST::ProcessedSource.new(code, RUBY_VERSION.to_f).ast
-      end
-
       def icon(args)
         return args.first.value.to_sym if args.first.type == :sym || args.first.type == :str
 

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ERBLint
+  module Linters
+    module Helpers
+      # Provides helpers related to RuboCop.
+      module RubocopHelpers
+        def erb_ast(code)
+          RuboCop::AST::ProcessedSource.new(code, RUBY_VERSION.to_f).ast
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ERBLint
+  module Linters
+    # Helpers used by linters to organize HTML tags into abstract syntax trees.
+    module TagTreeHelpers
+      # 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
+
+      # 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(processed_source)
+        nodes = processed_source.ast.children
+        tag_tree = {}
+        tags = []
+        current_opened_tag = nil
+
+        nodes.each do |node|
+          if node.type == :tag
+            # get the tag from previously calculated list so the references are the same
+            tag = BetterHtml::Tree::Tag.from_node(node)
+            tags << 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] = {
+              tag: tag,
+              closing: self_closing ? tag : nil,
+              parent: current_opened_tag,
+              children: []
+            }
+
+            tag_tree[current_opened_tag][:children] << tag_tree[tag] if current_opened_tag
+            current_opened_tag = tag unless self_closing
+          elsif current_opened_tag
+            tag_tree[current_opened_tag][:children] << node
+          end
+        end
+
+        [tags, tag_tree]
+      end
+
+      def self_closing?(tag)
+        tag.self_closing? || SELF_CLOSING_TAGS.include?(tag.name)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative "base_linter"
+require_relative "tag_tree_helpers"
+
+module ERBLint
+  module Linters
+    # Counts the number of times a two column layout using col-* CSS classes is used instead of the layout component.
+    class TwoColumnLayoutMigrationCounter < BaseLinter
+      include LinterRegistry
+      include TagTreeHelpers
+
+      WIDTH_RANGE = (8..10).freeze
+      SIDEBAR_WIDTH_RANGE = (2..4).freeze
+
+      CONTAINER_CLASSES = %w[container-xl container-lg container-md container-sm].freeze
+      MESSAGE = "We are migrating two-column layouts to use "\
+        "[Primer::Alpha::Layout](https://primer.style/view-components/components/layout), "\
+        "please use that instead of raw HTML."
+
+      # :nodoc:
+      class Breakpoints
+        LABELS = %i[all sm md lg xl].freeze
+
+        def initialize
+          @map = {}
+        end
+
+        def set(breakpoint, value)
+          @map[breakpoint] = value
+        end
+
+        def min
+          LABELS.find { |label| @map[label] } || :all
+        end
+
+        def min_value
+          @map[min]
+        end
+      end
+
+      # :nodoc:
+      class Column
+        attr_reader :widths, :tag_tree
+
+        def initialize(widths, tag_tree)
+          @widths = widths
+          @tag_tree = tag_tree
+        end
+      end
+
+      # :nodoc:
+      class Container
+        attr_reader :columns
+
+        def initialize(columns)
+          @columns = columns
+        end
+
+        def sidebar
+          sorted_columns.first
+        end
+
+        def main
+          sorted_columns.last
+        end
+
+        private
+
+        def sorted_columns
+          @sorted_columns ||= columns.sort_by do |col|
+            col.widths.min_value || 0
+          end
+        end
+      end
+
+      def run(processed_source)
+        @total_offenses = 0
+        @offenses_not_corrected = 0
+
+        tags, tag_tree = build_tag_tree(processed_source)
+
+        tags.each do |tag|
+          next if tag.closing?
+          next unless tag.name == "div"
+
+          classes = classes_from(tag)
+          next if (CONTAINER_CLASSES & classes).empty?
+
+          next unless metadata_from(tag_tree[tag])
+
+          @total_offenses += 1
+          @offenses_not_corrected += 1
+
+          generate_offense(self.class, processed_source, tag, MESSAGE)
+        end
+
+        counter_correct?(processed_source)
+      end
+
+      private
+
+      def metadata_from(tag_tree)
+        tags = tag_tree[:children].select { |c| c.is_a?(Hash) }
+
+        if d_flex?(tags)
+          container_from(tags.first)
+        else
+          container_from(tag_tree)
+        end
+      end
+
+      def d_flex?(tags)
+        tags.size == 1 && classes_from(tags.first[:tag]).include?("d-flex")
+      end
+
+      def container_from(columns_tag_tree)
+        columns = columns_from(columns_tag_tree)
+        return unless columns.size == 2
+
+        container = Container.new(columns)
+
+        main_min = container.main.widths.min_value
+        sidebar_min = container.sidebar.widths.min_value
+        return unless sidebar_min && main_min
+        return unless WIDTH_RANGE.include?(main_min)
+        return unless SIDEBAR_WIDTH_RANGE.include?(sidebar_min)
+
+        container
+      end
+
+      def columns_from(tag_tree)
+        tag_tree[:children].each_with_object([]) do |tag_data, tags_memo|
+          next unless tag_data.is_a?(Hash)
+          next unless tag_data[:tag].name == "div"
+
+          classes = classes_from(tag_data[:tag])
+          widths = Breakpoints.new
+
+          classes.each do |cls|
+            match = cls.match(/\Acol(?:-(xl|lg|md|sm))?-(\d{1,2})(?:-max)?\z/)
+            next unless match
+
+            breakpoint, width = match.captures
+            breakpoint ||= :all
+            widths.set(breakpoint.to_sym, width.to_i)
+          end
+
+          tags_memo << Column.new(widths, tag_data)
+        end
+      end
+
+      def classes_from(tag)
+        tag.attributes["class"]&.value&.split(" ") || []
+      end
+    end
+  end
+end

data/lib/primer/view_components/version.rb

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