primer_view_components 0.0.44 → 0.0.48

data/app/components/primer/beta/auto_complete/auto_complete.d.ts

@@ -0,0 +1 @@
+import '@github/auto-complete-element';

data/app/components/primer/beta/auto_complete/auto_complete.js

@@ -0,0 +1 @@
+import '@github/auto-complete-element';

data/app/components/primer/beta/auto_complete/item.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Primer
+  module Beta
+    class AutoComplete
+      # Use `AutoCompleteItem` to list results of an auto-completed search.
+      class Item < Primer::Component
+        status :beta
+
+        # @example Default
+        #   <%= render(Primer::Beta::AutoComplete::Item.new(selected: true, value: "value")) do |c| %>
+        #     Selected
+        #   <% end %>
+        #   <%= render(Primer::Beta::AutoComplete::Item.new(value: "value")) do |c| %>
+        #     Not selected
+        #   <% end %>
+        #
+        # @param value [String] Value of the item.
+        # @param selected [Boolean] Whether the item is selected.
+        # @param disabled [Boolean] Whether the item is disabled.
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(value:, selected: false, disabled: false, **system_arguments)
+          @system_arguments = system_arguments
+          @system_arguments[:tag] = :li
+          @system_arguments[:role] = :option
+          @system_arguments[:"data-autocomplete-value"] = value
+
+          @system_arguments[:"aria-selected"] = true if selected
+          @system_arguments[:"aria-disabled"] = true if disabled
+
+          @system_arguments[:classes] = class_names(
+            "autocomplete-item",
+            system_arguments[:classes],
+            "disabled" => disabled
+          )
+        end
+
+        def call
+          render(Primer::BaseComponent.new(**@system_arguments)) { content }
+        end
+      end
+    end
+  end
+end

data/app/components/primer/beta/avatar.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Primer
+  module Beta
+    # `Avatar` can be used to represent users and organizations on GitHub.
+    #
+    # - Use the default round avatar for users, and the `square` argument
+    # for organizations or any other non-human avatars.
+    # - By default, `Avatar` will render a static `<img>`. To have `Avatar` function as a link, set the `href` which will wrap the `<img>` in a `<a>`.
+    # - Set `size` to update the height and width of the `Avatar` in pixels.
+    # - To stack multiple avatars together, use <%= link_to_component(Primer::AvatarStackComponent) %>.
+    #
+    # @accessibility
+    #   Images should have text alternatives that describe the information or function represented.
+    #   If the avatar functions as a link, provide alt text that helps convey the function. For instance,
+    #   if `Avatar` is a link to a user profile, the alt attribute should be `@kittenuser profile`
+    #   rather than `@kittenuser`.
+    #   [Learn more about best image practices (WAI Images)](https://www.w3.org/WAI/tutorials/images/)
+    class Avatar < Primer::Component
+      status :beta
+
+      SMALL_THRESHOLD = 24
+
+      # @example Default
+      #   <%= render(Primer::Beta::Avatar.new(src: "http://placekitten.com/200/200", alt: "@kittenuser")) %>
+      #
+      # @example Square
+      #   <%= render(Primer::Beta::Avatar.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", square: true)) %>
+      #
+      # @example Link
+      #   <%= render(Primer::Beta::Avatar.new(href: "#", src: "http://placekitten.com/200/200", alt: "@kittenuser profile")) %>
+      #
+      # @example With size
+      #   <%= render(Primer::Beta::Avatar.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 16)) %>
+      #   <%= render(Primer::Beta::Avatar.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 20)) %>
+      #   <%= render(Primer::Beta::Avatar.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 24)) %>
+      #   <%= render(Primer::Beta::Avatar.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 28)) %>
+      #   <%= render(Primer::Beta::Avatar.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 32)) %>
+      #   <%= render(Primer::Beta::Avatar.new(src: "http://placekitten.com/200/200", alt: "@kittenuser", size: 36)) %>
+      #
+      # @param src [String] The source url of the avatar image.
+      # @param alt [String] Passed through to alt on img tag.
+      # @param size [Integer] Adds the avatar-small class if less than 24.
+      # @param square [Boolean] Used to create a square avatar.
+      # @param href [String] The URL to link to. If used, component will be wrapped by an `<a>` tag.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(src:, alt:, size: 20, square: false, href: nil, **system_arguments)
+        @href = href
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :img
+        @system_arguments[:src] = src
+        @system_arguments[:alt] = alt
+        @system_arguments[:size] = size
+        @system_arguments[:height] = size
+        @system_arguments[:width] = size
+
+        @system_arguments[:classes] = class_names(
+          system_arguments[:classes],
+          "avatar",
+          "avatar-small" => size < SMALL_THRESHOLD,
+          "circle" => !square,
+          "lh-0" => href # Addresses an overflow issue with linked avatars
+        )
+      end
+
+      def call
+        if @href
+          render(Primer::LinkComponent.new(href: @href, classes: @system_arguments[:classes])) do
+            render(Primer::BaseComponent.new(**@system_arguments.except(:classes))) { content }
+          end
+        else
+          render(Primer::BaseComponent.new(**@system_arguments)) { content }
+        end
+      end
+    end
+  end
+end

data/app/components/primer/border_box_component.rb

@@ -11,6 +11,7 @@ module Primer
       :condensed => "Box--condensed",
       :spacious => "Box--spacious"
     }.freeze
+    PADDING_SUGGESTION = "Perhaps you could consider using :padding options of #{PADDING_MAPPINGS.keys.to_sentence}?"
 
     # Optional Header.
     #
@@ -111,6 +112,8 @@ module Primer
         PADDING_MAPPINGS[fetch_or_fallback(PADDING_MAPPINGS.keys, padding, DEFAULT_PADDING)],
         system_arguments[:classes]
       )
+
+      @system_arguments[:system_arguments_denylist] = { [:p, :pt, :pb, :pr, :pl] => PADDING_SUGGESTION }
     end
 
     def render?

data/app/components/primer/clipboard_copy.rb

@@ -2,25 +2,43 @@
 
 module Primer
   # Use `ClipboardCopy` to copy element text content or input values to the clipboard.
+  #
+  # @accessibility
+  #   Always set an accessible label to help the user interact with the component.
   class ClipboardCopy < Primer::Component
     status :alpha
 
     # @example Default
-    #   <%= render(Primer::ClipboardCopy.new(value: "Text to copy", label: "Copy text to the system clipboard")) %>
+    #   <%= render(Primer::ClipboardCopy.new(value: "Text to copy", "aria-label": "Copy text to the system clipboard")) %>
     #
     # @example With text instead of icons
-    #   <%= render(Primer::ClipboardCopy.new(value: "Text to copy", label: "Copy text to the system clipboard")) do %>
+    #   <%= render(Primer::ClipboardCopy.new(value: "Text to copy", "aria-label": "Copy text to the system clipboard")) do %>
     #     Click to copy!
     #   <% end %>
     #
-    # @param label [String] String that will be read to screenreaders when the component is focused
-    # @param value [String] Text to copy into the users clipboard when they click the component
+    # @example Copying from an element
+    #   <%= render(Primer::ClipboardCopy.new(for: "blob-path", "aria-label": "Copy text to the system clipboard")) %>
+    #   <div id="blob-path">src/index.js</div>
+    #
+    # @param aria-label [String] String that will be read to screenreaders when the component is focused
+    # @param value [String] Text to copy into the users clipboard when they click the component.
+    # @param for [String] Element id from where to get the copied value.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    def initialize(label:, value:, **system_arguments)
+    def initialize(value: nil, **system_arguments)
       @system_arguments = system_arguments
+      @value = value
+
+      validate!
+
       @system_arguments[:tag] = "clipboard-copy"
-      @system_arguments[:value] = value
-      @system_arguments[:"aria-label"] = label
+      @system_arguments[:value] = value if value.present?
+    end
+
+    private
+
+    def validate!
+      validate_aria_label
+      raise ArgumentError, "Must provide either `value` or `for`" if @value.nil? && @system_arguments[:for].nil?
     end
   end
 end

data/app/components/primer/component.rb

@@ -15,6 +15,10 @@ module Primer
 
     private
 
+    def force_system_arguments?
+      Rails.application.config.primer_view_components.force_system_arguments
+    end
+
     def deprecated_component_warning(new_class: nil, version: nil)
       return if Rails.env.production? || silence_deprecations?
 
@@ -25,8 +29,12 @@ module Primer
       ActiveSupport::Deprecation.warn(message)
     end
 
+    def aria(val, system_arguments)
+      system_arguments[:"aria-#{val}"] || system_arguments.dig(:aria, val.to_sym)
+    end
+
     def validate_aria_label
-      aria_label = @system_arguments[:"aria-label"] || @system_arguments.dig(:aria, :label)
+      aria_label = aria("label", @system_arguments)
       raise ArgumentError, "`aria-label` is required." if aria_label.nil? && !Rails.env.production?
     end
 

data/app/components/primer/details_component.rb

@@ -5,6 +5,8 @@ module Primer
   class DetailsComponent < Primer::Component
     status :beta
 
+    BODY_TAG_DEFAULT = :div
+    BODY_TAG_OPTIONS = [:ul, :"details-menu", :"details-dialog", BODY_TAG_DEFAULT].freeze
     NO_OVERLAY = :none
     OVERLAY_MAPPINGS = {
       NO_OVERLAY => "",
@@ -27,21 +29,23 @@ module Primer
 
     # Use the Body slot as the main content to be shown when triggered by the Summary.
     #
+    # @param tag [Symbol] (Primer::DetailsComponent::BODY_TAG_DEFAULT) <%= one_of(Primer::DetailsComponent::BODY_TAG_OPTIONS) %>
     # @param kwargs [Hash] The same arguments as <%= link_to_system_arguments_docs %>.
-    renders_one :body, lambda { |**system_arguments|
-      system_arguments[:tag] ||= :div
+    renders_one :body, lambda { |tag: BODY_TAG_DEFAULT, **system_arguments|
+      system_arguments[:tag] = fetch_or_fallback(BODY_TAG_OPTIONS, tag, BODY_TAG_DEFAULT)
+
       Primer::BaseComponent.new(**system_arguments)
     }
 
     # @example Default
     #
     #   <%= render Primer::DetailsComponent.new do |c| %>
-    #     component.summary do
-    #       "Summary"
-    #     end
-    #     component.body do
-    #       "Body"
-    #     end
+    #     <% c.summary do %>
+    #       Summary
+    #     <% end %>
+    #     <% c.body do %>
+    #       Body
+    #     <% end %>
     #   <% end %>
     #
     # @param overlay [Symbol] Dictates the type of overlay to render with. <%= one_of(Primer::DetailsComponent::OVERLAY_MAPPINGS.keys) %>

data/app/components/primer/image_crop.rb

@@ -6,7 +6,7 @@ module Primer
     # A loading indicator that is shown while the image is loading.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     renders_one :loading, lambda { |**system_arguments|
-      system_arguments[:tag] ||= :div
+      system_arguments[:tag] = :div
       system_arguments[:"data-loading-slot"] = true
 
       Primer::BaseComponent.new(**system_arguments)

data/app/components/primer/markdown.rb

@@ -99,17 +99,17 @@ module Primer
     #     <p>And an unordered task list:</p>
     #
     #     <ul>
-    #       <li><input type="checkbox" checked /> Create a sample markdown document</li>
-    #       <li><input type="checkbox"/> Add task lists to it</li>
-    #       <li><input type="checkbox"/> Take a vacation</li>
+    #       <li><input type="checkbox" id="create-markdown" checked /><label for="create-markdown">Create a sample markdown document</label><br></li>
+    #       <li><input type="checkbox" id="tasks-list" checked /><label for="tasks-list">Add tasks list to it</label><br></li>
+    #       <li><input type="checkbox" id="take-vacation" checked /><label for="take-vacation">Take a vacation</label><br></li>
     #     </ul>
     #
     #     <p>And a "mixed" task list:</p>
     #
     #     <ul>
-    #       <li><input type="checkbox"/> Steal underpants</li>
+    #       <li><input type="checkbox"id="steal-underpants"/><label for="steal-underpants">Steal underpants</label></li>
     #       <li>?</li>
-    #       <li><input type="checkbox"/> Profit!</li>
+    #       <li><input type="checkbox"id="profit"/><label for="profit">Profit!</label></li>
     #     </ul>
     #
     #     And a nested list:
@@ -241,9 +241,9 @@ module Primer
     #
     #     <pre><code>var foo = "bar";</code></pre>
     #
-    #     <pre><code>Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.</code></pre>
+    #     <pre tabindex="0"><code>Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.</code></pre>
     #
-    #     <pre><code>var foo = "The same thing is true for code with syntax highlighting. A single line of code should horizontally scroll if it is really long.";</code></pre>
+    #     <pre tabindex="0"><code>var foo = "The same thing is true for code with syntax highlighting. A single line of code should horizontally scroll if it is really long.";</code></pre>
     #
     #     <p>Inline code inside table cells should still be distinguishable.</p>
     #
@@ -270,11 +270,11 @@ module Primer
     #
     #     <p>Small images should be shown at their actual size.</p>
     #
-    #     <p><img src="http://placekitten.com/g/300/200/"/></p>
+    #     <p><img alt="kitten" src="http://placekitten.com/g/300/200/"/></p>
     #
     #     <p>Large images should always scale down and fit in the content container.</p>
     #
-    #     <p><img src="http://placekitten.com/g/1200/800/"/></p>
+    #     <p><img alt="kitten" src="http://placekitten.com/g/1200/800/"/></p>
     #
     #     <pre><code>This is the final element on the page and there should be no margin below this.</code></pre>
     #   <% end %>

data/app/components/primer/menu_component.rb

@@ -3,11 +3,15 @@
 module Primer
   # Use `Menu` to create vertical lists of navigational links.
   class MenuComponent < Primer::Component
+    HEADING_TAG_OPTIONS = [:h1, :h2, :h3, :h4, :h5, :h6].freeze
+    HEADING_TAG_FALLBACK = :h2
+
     # Optional menu heading
     #
+    # @param tag [Symbol] <%= one_of(Primer::MenuComponent::HEADING_TAG_OPTIONS) %>
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    renders_one :heading, lambda { |**system_arguments|
-      system_arguments[:tag] ||= :span
+    renders_one :heading, lambda { |tag:, **system_arguments|
+      system_arguments[:tag] = fetch_or_fallback(HEADING_TAG_OPTIONS, tag, HEADING_TAG_FALLBACK)
       system_arguments[:classes] = class_names(
         "menu-heading",
         system_arguments[:classes]
@@ -35,7 +39,7 @@ module Primer
 
     # @example Default
     #   <%= render(Primer::MenuComponent.new) do |c| %>
-    #     <% c.heading do %>
+    #     <% c.heading(tag: :h2) do %>
     #       Heading
     #     <% end %>
     #     <% c.item(selected: true, href: "#url") do %>

data/app/components/primer/navigation/tab_component.rb

@@ -18,10 +18,22 @@ module Primer
       #
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
       renders_one :panel, lambda { |**system_arguments|
-        system_arguments[:tag] ||= :div
+        return unless @with_panel
+
+        system_arguments[:tag] = :div
         system_arguments[:role] ||= :tabpanel
+        system_arguments[:tabindex] = 0
         system_arguments[:hidden] = true unless @selected
 
+        label_present = aria("label", system_arguments) || aria("labelledby", system_arguments)
+        unless label_present
+          if @id.present?
+            system_arguments[:"aria-labelledby"] = @id
+          elsif !Rails.env.production?
+            raise ArgumentError, "Panels must be labelled. Either set a unique `id` on the tab, or set an `aria-label` directly on the panel"
+          end
+        end
+
         Primer::BaseComponent.new(**system_arguments)
       }
 
@@ -93,15 +105,17 @@ module Primer
         @selected = selected
         @icon_classes = icon_classes
         @list = list
+        @with_panel = with_panel
 
         @system_arguments = system_arguments
+        @id = @system_arguments[:id]
 
-        if with_panel
-          @system_arguments[:tag] ||= :button
+        if with_panel || @system_arguments[:tag] == :button
+          @system_arguments[:tag] = :button
           @system_arguments[:type] = :button
           @system_arguments[:role] = :tab
         else
-          @system_arguments[:tag] ||= :a
+          @system_arguments[:tag] = :a
         end
 
         @wrapper_arguments = wrapper_arguments
@@ -111,7 +125,7 @@ module Primer
         return unless @selected
 
         if @system_arguments[:tag] == :a
-          aria_current = @system_arguments[:"aria-current"] || @system_arguments.dig(:aria, :current) || DEFAULT_ARIA_CURRENT_FOR_ANCHOR
+          aria_current = aria("current", system_arguments) || DEFAULT_ARIA_CURRENT_FOR_ANCHOR
           @system_arguments[:"aria-current"] = fetch_or_fallback(ARIA_CURRENT_OPTIONS_FOR_ANCHOR, aria_current, DEFAULT_ARIA_CURRENT_FOR_ANCHOR)
         else
           @system_arguments[:"aria-selected"] = true

data/app/components/primer/popover_component.rb

@@ -23,12 +23,15 @@ module Primer
       :top_right => "Popover-message--top-right"
     }.freeze
 
+    DEFAULT_HEADING_TAG = :h4
+
     # The heading
     #
+    # @param tag [Symbol] (Primer::PopoverComponent::DEFAULT_HEADING_TAG) <%= one_of(Primer::HeadingComponent::TAG_OPTIONS) %>
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    renders_one :heading, lambda { |**system_arguments|
+    renders_one :heading, lambda { |tag: DEFAULT_HEADING_TAG, **system_arguments|
+      system_arguments[:tag] = tag
       system_arguments[:mb] ||= 2
-      system_arguments[:tag] ||= :h4
 
       Primer::HeadingComponent.new(**system_arguments)
     }
@@ -106,7 +109,7 @@ module Primer
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(**system_arguments)
       @system_arguments = system_arguments
-      @system_arguments[:tag] ||= :div
+      @system_arguments[:tag] = :div
       @system_arguments[:classes] = class_names(
         system_arguments[:classes],
         "Popover"

data/app/components/primer/primer.d.ts

@@ -1,4 +1,4 @@
-import './auto_complete/auto_complete';
+import './beta/auto_complete/auto_complete';
 import './clipboard_copy_component';
 import './tab_container_component';
 import './time_ago_component';

data/app/components/primer/primer.js

@@ -1,4 +1,4 @@
-import './auto_complete/auto_complete';
+import './beta/auto_complete/auto_complete';
 import './clipboard_copy_component';
 import './tab_container_component';
 import './time_ago_component';