primer_view_components 0.0.43 → 0.0.47

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

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Primer
+  module Beta
+    # Use `AutoComplete` to provide a user with a list of selectable suggestions that appear when they type into the
+    # input field. This list is populated by server search results.
+    # @accessibility
+    #   Always set an accessible label to help the user interact with the component.
+    #
+    #   * Set the `label` slot to render a visible label. Alternatively, associate an existing visible text element
+    #   as a label by setting `aria-labelledby`.
+    #   * If you must use a non-visible label, set `:"aria-label"` on `AutoComplete` and Primer
+    #   will apply it to the correct elements. However, please note that a visible label should almost
+    #   always be used unless there is compelling reason not to. A placeholder is not a label.
+    class AutoComplete < Primer::Component
+      status :beta
+
+      # Optionally render a visible label. See <%= link_to_accessibility %>
+      #
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :label, lambda { |**system_arguments|
+        system_arguments[:for] = @input_id
+        system_arguments[:tag] = :label
+        Primer::BaseComponent.new(**system_arguments)
+      }
+
+      # Required input used to search for results
+      #
+      # @param type [Symbol] <%= one_of(Primer::Beta::AutoComplete::Input::TYPE_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :input, lambda { |**system_arguments|
+        aria_label = system_arguments[:"aria-label"] || system_arguments.dig(:aria, :label) || @aria_label
+        if aria_label.present?
+          system_arguments[:"aria-label"] = aria_label
+          system_arguments[:aria]&.delete(:label)
+        end
+
+        name = system_arguments[:name] || @input_id
+        Input.new(id: @input_id, name: name, **system_arguments)
+      }
+
+      # Optional icon to be rendered before the input. Has the same arguments as <%= link_to_component(Primer::OcticonComponent) %>.
+      #
+      renders_one :icon, Primer::OcticonComponent
+
+      # Customizable results list.
+      #
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :results, lambda { |**system_arguments|
+        system_arguments[:tag] = :ul
+        system_arguments[:id] = @list_id
+        system_arguments[:classes] = class_names(
+          "autocomplete-results",
+          system_arguments[:classes]
+        )
+
+        aria_label = system_arguments[:"aria-label"] || system_arguments.dig(:aria, :label) || @aria_label
+        system_arguments[:"aria-label"] = aria_label if aria_label.present?
+        system_arguments[:aria]&.delete(:label)
+
+        Primer::BaseComponent.new(**system_arguments)
+      }
+
+      # @example Default
+      #   <%= render(Primer::Beta::AutoComplete.new(src: "/auto_complete", input_id: "fruits-input-1", list_id: "fruits-popup-1", position: :relative)) do |c| %>
+      #     <% c.label(classes:"").with_content("Fruits") %>
+      #     <% c.input(type: :text) %>
+      #   <% end %>
+      #
+      # @example With `aria-label`
+      #   <%= render(Primer::Beta::AutoComplete.new("aria-label": "Fruits", src: "/auto_complete", input_id: "fruits-input-2", list_id: "fruits-popup-2", position: :relative)) do |c| %>
+      #     <% c.input(type: :text) %>
+      #   <% end %>
+      #
+      # @example With `aria-labelledby`
+      #   <%= render(Primer::HeadingComponent.new(tag: :h2, id: "search-1")) { "Search" } %>
+      #   <%= render(Primer::Beta::AutoComplete.new(src: "/auto_complete", input_id: "fruits-input-3", list_id: "fruits-popup-2", position: :relative)) do |c| %>
+      #     <% c.input("aria-labelledby": "search-1") %>
+      #   <% end %>
+      #
+      # @example With custom classes for the results
+      #   <%= render(Primer::Beta::AutoComplete.new(src: "/auto_complete", input_id: "fruits-input-4", list_id: "fruits-popup-3", position: :relative)) do |c| %>
+      #     <% c.label(classes:"").with_content("Fruits") %>
+      #     <% c.input(type: :text) %>
+      #     <% c.results(classes: "custom-class") do %>
+      #       <%= render(Primer::Beta::AutoComplete::Item.new(selected: true, value: "apple")) do |c| %>
+      #         Apple
+      #       <% end %>
+      #       <%= render(Primer::Beta::AutoComplete::Item.new(value: "orange")) do |c| %>
+      #         Orange
+      #       <% end %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # @example With Icon
+      #   <%= render(Primer::Beta::AutoComplete.new(src: "/auto_complete", list_id: "fruits-popup-4", input_id: "fruits-input-4", position: :relative)) do |c| %>
+      #     <% c.label(classes:"").with_content("Fruits") %>
+      #     <% c.input(type: :text) %>
+      #     <% c.icon(icon: :search) %>
+      #   <% end %>
+      #
+      # @param src [String] The route to query.
+      # @param input_id [String] Id of the input element.
+      # @param list_id [String] Id of the list element.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(src:, list_id:, input_id:, **system_arguments)
+        @list_id = list_id
+        @input_id = input_id
+        @aria_label = system_arguments[:"aria-label"] || system_arguments.dig(:aria, :label)
+
+        system_arguments.delete(:"aria-label") && system_arguments[:aria]&.delete(:label)
+
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = "auto-complete"
+        @system_arguments[:src] = src
+        @system_arguments[:for] = list_id
+      end
+
+      # add `results` without needing to explicitly call it in the view
+      def before_render
+        raise ArgumentError, "Missing `input` slot" if input.blank?
+        raise ArgumentError, "Accessible label is required." if label.blank? && input.missing_label?
+
+        results(classes: "") unless results
+      end
+
+      # This component is part of `Primer::Beta::AutoCompleteComponent` and should not be
+      # used as a standalone component.
+      class Input < Primer::Component
+        DEFAULT_TYPE = :text
+        TYPE_OPTIONS = [DEFAULT_TYPE, :search].freeze
+
+        # @param type [Symbol] <%= one_of(Primer::Beta::AutoComplete::Input::TYPE_OPTIONS) %>
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(type: DEFAULT_TYPE, **system_arguments)
+          @system_arguments = system_arguments
+          @system_arguments[:tag] = :input
+
+          @aria_label = system_arguments[:"aria-label"]
+          @aria_labelledby = system_arguments[:"aria-labelledby"] || system_arguments.dig(:aria, :labelledby)
+
+          @system_arguments[:type] = fetch_or_fallback(TYPE_OPTIONS, type, DEFAULT_TYPE)
+          @system_arguments[:classes] = class_names(
+            "form-control",
+            system_arguments[:classes]
+          )
+        end
+
+        def missing_label?
+          @aria_label.blank? && @aria_labelledby.blank?
+        end
+
+        def call
+          render(Primer::BaseComponent.new(**@system_arguments))
+        end
+      end
+    end
+  end
+end

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

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

data/app/components/primer/{auto_complete → beta/auto_complete}/auto_complete.html.erb

@@ -1,3 +1,4 @@
+<%= label %>
 <%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <%= input %>
   <%= icon %>

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/beta/text.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Primer
+  module Beta
+    # `Text` is a wrapper component that will apply typography styles to the text inside.
+    class Text < Primer::Component
+      status :beta
+
+      DEFAULT_TAG = :span
+
+      # @example Default
+      #   <%= render(Primer::Beta::Text.new(tag: :p, font_weight: :bold)) { "Bold Text" } %>
+      #   <%= render(Primer::Beta::Text.new(tag: :p, color: :text_danger)) { "Danger Text" } %>
+      #
+      # @param tag [Symbol]
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(tag: DEFAULT_TAG, **system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = tag
+      end
+
+      def call
+        render(Primer::BaseComponent.new(**@system_arguments)) { content }
+      end
+    end
+  end
+end

data/app/components/primer/blankslate_component.rb

@@ -95,7 +95,7 @@ module Primer
     # @param title [String] Text that appears in a larger bold font.
     # @param title_tag [Symbol] HTML tag to use for title.
     # @param icon [Symbol] Octicon icon to use at top of component.
-    # @param icon_size [Symbol] <%= one_of(Primer::OcticonComponent::SIZE_MAPPINGS) %>
+    # @param icon_size [Symbol] <%= one_of(Primer::OcticonComponent::SIZE_MAPPINGS, sort: false) %>
     # @param image_src [String] Image to display.
     # @param image_alt [String] Alt text for image.
     # @param description [String] Text that appears below the title. Typically a whole sentence.
@@ -107,6 +107,7 @@ module Primer
     # @param narrow [Boolean] Adds a maximum width.
     # @param large [Boolean] Increases the font size.
     # @param spacious [Boolean] Adds extra padding.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(
       title: "",
       title_tag: :h3,

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/button_component.rb

@@ -78,11 +78,12 @@ module Primer
     #
     # @param scheme [Symbol] <%= one_of(Primer::ButtonComponent::SCHEME_OPTIONS) %>
     # @param variant [Symbol] <%= one_of(Primer::ButtonComponent::VARIANT_OPTIONS) %>
-    # @param tag [Symbol] <%= one_of(Primer::BaseButton::TAG_OPTIONS) %>
-    # @param type [Symbol] <%= one_of(Primer::BaseButton::TYPE_OPTIONS) %>
+    # @param tag [Symbol] (Primer::BaseButton::DEFAULT_TAG) <%= one_of(Primer::BaseButton::TAG_OPTIONS) %>
+    # @param type [Symbol] (Primer::BaseButton::DEFAULT_TYPE) <%= one_of(Primer::BaseButton::TYPE_OPTIONS) %>
     # @param group_item [Boolean] Whether button is part of a ButtonGroup.
     # @param block [Boolean] Whether button is full-width with `display: block`.
     # @param caret [Boolean] Whether or not to render a caret.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     def initialize(
       scheme: DEFAULT_SCHEME,
       variant: DEFAULT_VARIANT,

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?
 

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 => "",
@@ -14,7 +16,7 @@ module Primer
 
     # Use the Summary slot as a trigger to reveal the content.
     #
-    # @param button [Boolean] Whether to render the Summary as a button or not.
+    # @param button [Boolean] (true) Whether to render the Summary as a button or not.
     # @param kwargs [Hash] The same arguments as <%= link_to_system_arguments_docs %>.
     renders_one :summary, lambda { |button: true, **system_arguments|
       system_arguments[:tag] = :summary
@@ -27,12 +29,25 @@ 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| %>
+    #     <% 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) %>
     # @param reset [Boolean] Defatuls to false. If set to true, it will remove the default caret and remove style from the summary element
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>