primer_view_components 0.0.68 → 0.0.71

data/app/components/primer/alpha/tooltip.ts

@@ -0,0 +1,383 @@
+import type {AnchorAlignment, AnchorSide} from '@primer/behaviors'
+import {getAnchoredPosition} from '@primer/behaviors'
+
+const TOOLTIP_OPEN_CLASS = 'tooltip-open'
+const TOOLTIP_ARROW_EDGE_OFFSET = 10
+
+type Direction = 'n' | 's' | 'e' | 'w' | 'ne' | 'se' | 'nw' | 'sw'
+
+const DIRECTION_CLASSES = [
+  'tooltip-n',
+  'tooltip-s',
+  'tooltip-e',
+  'tooltip-w',
+  'tooltip-ne',
+  'tooltip-se',
+  'tooltip-nw',
+  'tooltip-sw'
+]
+
+class TooltipElement extends HTMLElement {
+  styles() {
+    return `
+      :host {
+        position: absolute;
+        z-index: 1000000;
+        padding: .5em .75em;
+        font: normal normal 11px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
+        -webkit-font-smoothing: subpixel-antialiased;
+        color: var(--color-fg-on-emphasis);
+        text-align: center;
+        text-decoration: none;
+        text-shadow: none;
+        text-transform: none;
+        letter-spacing: normal;
+        word-wrap: break-word;
+        white-space: pre;
+        background: var(--color-neutral-emphasis-plus);
+        border-radius: 6px;
+        opacity: 0;
+        max-width: 250px;
+        word-wrap: break-word;
+        white-space: normal;
+        width: max-content;
+      }
+      
+      :host:before{
+        position: absolute;
+        z-index: 1000001;
+        color: var(--color-neutral-emphasis-plus);
+        content: "";
+        border: 6px solid transparent;
+        opacity: 0
+      }
+      
+      @keyframes tooltip-appear {
+        from {
+          opacity: 0
+        }
+        to {
+          opacity: 1
+        }
+      }
+      
+      :host:after{
+        position: absolute;
+        display: block;
+        right: 0;
+        left: 0;
+        height: 12px;
+        content: ""
+      }
+      
+      :host(.${TOOLTIP_OPEN_CLASS}),
+      :host(.${TOOLTIP_OPEN_CLASS}):before {
+        animation-name: tooltip-appear;
+        animation-duration: .1s;
+        animation-fill-mode: forwards;
+        animation-timing-function: ease-in;
+        animation-delay: .4s
+      }
+      
+      :host(.tooltip-s):before,
+      :host(.tooltip-n):before {
+        right: 50%;
+      }
+
+      :host(.tooltip-s):before,
+      :host(.tooltip-se):before,
+      :host(.tooltip-sw):before {
+        bottom: 100%;
+        margin-right: -${TOOLTIP_ARROW_EDGE_OFFSET}px;
+        border-bottom-color: var(--color-neutral-emphasis-plus)
+      }
+      
+      :host(.tooltip-s):after,
+      :host(.tooltip-se):after,
+      :host(.tooltip-sw):after {
+        bottom: 100%
+      }
+      
+      :host(.tooltip-n):before,
+      :host(.tooltip-ne):before,
+      :host(.tooltip-nw):before {
+        top: 100%;
+        margin-right: -${TOOLTIP_ARROW_EDGE_OFFSET}px;
+        border-top-color: var(--color-neutral-emphasis-plus)
+      }
+      
+      :host(.tooltip-n):after,
+      :host(.tooltip-ne):after,
+      :host(.tooltip-nw):after {
+        top: 100%
+      }
+      
+      :host(.tooltip-se):before,
+      :host(.tooltip-ne):before {
+        left: 0;
+        margin-left: ${TOOLTIP_ARROW_EDGE_OFFSET}px;
+      }
+      
+      :host(.tooltip-sw):before,
+      :host(.tooltip-nw):before {
+        right: 0;
+        margin-right: ${TOOLTIP_ARROW_EDGE_OFFSET}px;
+      }
+      
+      :host(.tooltip-w):before {
+        top: 50%;
+        bottom: 50%;
+        left: 100%;
+        margin-top: -6px;
+        border-left-color: var(--color-neutral-emphasis-plus)
+      }
+      
+      :host(.tooltip-e):before {
+        top: 50%;
+        right: 100%;
+        bottom: 50%;
+        margin-top: -6px;
+        border-right-color: var(--color-neutral-emphasis-plus)
+      }
+    `
+  }
+
+  #abortController: AbortController | undefined
+  #align: AnchorAlignment = 'center'
+  #side: AnchorSide = 'outside-bottom'
+  #allowUpdatePosition = false
+
+  get htmlFor(): string {
+    return this.getAttribute('for') || ''
+  }
+
+  set htmlFor(value: string) {
+    this.setAttribute('for', value)
+  }
+
+  get type(): 'description' | 'label' {
+    const type = this.getAttribute('data-type')
+    return type === 'label' ? 'label' : 'description'
+  }
+
+  set type(value: 'description' | 'label') {
+    this.setAttribute('data-type', value)
+  }
+
+  get direction(): Direction {
+    return (this.getAttribute('data-direction') || 's') as Direction
+  }
+
+  set direction(value: Direction) {
+    this.setAttribute('data-direction', value)
+  }
+
+  get control(): HTMLElement | null {
+    return this.ownerDocument.getElementById(this.htmlFor)
+  }
+
+  constructor() {
+    super()
+    const shadow = this.attachShadow({mode: 'open'})
+    shadow.innerHTML = `
+      <style>
+        ${this.styles()}
+      </style>
+      <slot></slot>
+    `
+  }
+
+  connectedCallback() {
+    this.hidden = true
+    this.#allowUpdatePosition = true
+
+    if (!this.id) {
+      this.id = `tooltip-${Date.now()}-${(Math.random() * 10000).toFixed(0)}`
+    }
+
+    if (!this.control) return
+
+    this.setAttribute('role', 'tooltip')
+
+    this.#abortController?.abort()
+    this.#abortController = new AbortController()
+    const {signal} = this.#abortController
+
+    this.addEventListener('mouseleave', this, {signal})
+    this.control.addEventListener('mouseenter', this, {signal})
+    this.control.addEventListener('mouseleave', this, {signal})
+    this.control.addEventListener('focus', this, {signal})
+    this.control.addEventListener('blur', this, {signal})
+    this.ownerDocument.addEventListener('keydown', this, {signal})
+  }
+
+  disconnectedCallback() {
+    this.#abortController?.abort()
+  }
+
+  handleEvent(event: Event) {
+    if (!this.control) return
+
+    // Ensures that tooltip stays open when hovering between tooltip and element
+    // WCAG Success Criterion 1.4.13 Hoverable
+    if ((event.type === 'mouseenter' || event.type === 'focus') && this.hidden) {
+      this.hidden = false
+    } else if (event.type === 'blur') {
+      this.hidden = true
+    } else if (
+      event.type === 'mouseleave' &&
+      (event as MouseEvent).relatedTarget !== this.control &&
+      (event as MouseEvent).relatedTarget !== this
+    ) {
+      this.hidden = true
+    } else if (event.type === 'keydown' && (event as KeyboardEvent).key === 'Escape' && !this.hidden) {
+      this.hidden = true
+    }
+  }
+
+  static observedAttributes = ['data-type', 'data-direction', 'id', 'hidden']
+
+  attributeChangedCallback(name: string) {
+    if (name === 'id' || name === 'data-type') {
+      if (!this.id || !this.control) return
+      if (this.type === 'label') {
+        this.control.setAttribute('aria-labelledby', this.id)
+      } else {
+        let describedBy = this.control.getAttribute('aria-describedby')
+        describedBy ? (describedBy = `${describedBy} ${this.id}`) : (describedBy = this.id)
+        this.control.setAttribute('aria-describedby', describedBy)
+      }
+    } else if (name === 'hidden') {
+      if (this.hidden) {
+        this.classList.remove(TOOLTIP_OPEN_CLASS, ...DIRECTION_CLASSES)
+      } else {
+        this.classList.add(TOOLTIP_OPEN_CLASS)
+        for (const tooltip of this.ownerDocument.querySelectorAll<HTMLElement>(this.tagName)) {
+          if (tooltip !== this) tooltip.hidden = true
+        }
+        this.#updatePosition()
+      }
+    } else if (name === 'data-direction') {
+      this.classList.remove(...DIRECTION_CLASSES)
+      const direction = this.direction
+      if (direction === 'n') {
+        this.#align = 'center'
+        this.#side = 'outside-top'
+      } else if (direction === 'ne') {
+        this.#align = 'start'
+        this.#side = 'outside-top'
+      } else if (direction === 'e') {
+        this.#align = 'center'
+        this.#side = 'outside-right'
+      } else if (direction === 'se') {
+        this.#align = 'start'
+        this.#side = 'outside-bottom'
+      } else if (direction === 's') {
+        this.#align = 'center'
+        this.#side = 'outside-bottom'
+      } else if (direction === 'sw') {
+        this.#align = 'end'
+        this.#side = 'outside-bottom'
+      } else if (direction === 'w') {
+        this.#align = 'center'
+        this.#side = 'outside-left'
+      } else if (direction === 'nw') {
+        this.#align = 'end'
+        this.#side = 'outside-top'
+      }
+    }
+  }
+
+  // `getAnchoredPosition` may calibrate `anchoredSide` but does not recalibrate `align`.
+  //  Therefore, we need to determine which `align` is best based on the initial `getAnchoredPosition` calcluation.
+  //  Related: https://github.com/primer/behaviors/issues/63
+  #adjustedAnchorAlignment(anchorSide: AnchorSide): AnchorAlignment | undefined {
+    if (!this.control) return
+
+    const tooltipPosition = this.getBoundingClientRect()
+    const targetPosition = this.control.getBoundingClientRect()
+    const tooltipWidth = tooltipPosition.width
+
+    const tooltipCenter = tooltipPosition.left + tooltipWidth / 2
+    const targetCenter = targetPosition.x + targetPosition.width / 2
+
+    if (Math.abs(tooltipCenter - targetCenter) < 2 || anchorSide === 'outside-left' || anchorSide === 'outside-right') {
+      return 'center'
+    } else if (tooltipPosition.left === targetPosition.left) {
+      return 'start'
+    } else if (tooltipPosition.right === targetPosition.right) {
+      return 'end'
+    } else if (tooltipCenter < targetCenter) {
+      if (tooltipPosition.left === 0) return 'start'
+      return 'end'
+    } else {
+      if (tooltipPosition.right === 0) return 'end'
+      return 'start'
+    }
+  }
+
+  #updatePosition() {
+    if (!this.control) return
+    if (!this.#allowUpdatePosition || this.hidden) return
+
+    const TOOLTIP_OFFSET = 10
+
+    this.style.left = `0px` // Ensures we have reliable tooltip width in `getAnchoredPosition`
+    let position = getAnchoredPosition(this, this.control, {
+      side: this.#side,
+      align: this.#align,
+      anchorOffset: TOOLTIP_OFFSET
+    })
+    let anchorSide = position.anchorSide
+
+    // We need to set tooltip position in order to determine ideal align.
+    this.style.top = `${position.top}px`
+    this.style.left = `${position.left}px`
+    let direction: Direction = 's'
+
+    const align = this.#adjustedAnchorAlignment(anchorSide)
+    if (!align) return
+
+    this.style.left = `0px` // Reset tooltip position again to ensure accurate width in `getAnchoredPosition`
+    position = getAnchoredPosition(this, this.control, {side: anchorSide, align, anchorOffset: TOOLTIP_OFFSET})
+    anchorSide = position.anchorSide
+
+    this.style.top = `${position.top}px`
+    this.style.left = `${position.left}px`
+
+    if (anchorSide === 'outside-left') {
+      direction = 'w'
+    } else if (anchorSide === 'outside-right') {
+      direction = 'e'
+    } else if (anchorSide === 'outside-top') {
+      if (align === 'center') {
+        direction = 'n'
+      } else if (align === 'start') {
+        direction = 'ne'
+      } else {
+        direction = 'nw'
+      }
+    } else {
+      if (align === 'center') {
+        direction = 's'
+      } else if (align === 'start') {
+        direction = 'se'
+      } else {
+        direction = 'sw'
+      }
+    }
+
+    this.classList.add(`tooltip-${direction}`)
+  }
+}
+
+if (!window.customElements.get('tool-tip')) {
+  window.TooltipElement = TooltipElement
+  window.customElements.define('tool-tip', TooltipElement)
+}
+
+declare global {
+  interface Window {
+    TooltipElement: typeof TooltipElement
+  }
+}

data/app/components/primer/base_component.rb

@@ -5,7 +5,7 @@ require "primer/classify"
 module Primer
   # All Primer ViewComponents accept a standard set of options called system arguments, mimicking the [styled-system API](https://styled-system.com/table) used by [Primer React](https://primer.style/components/system-props).
   #
-  # Under the hood, system arguments are [mapped](https://github.com/primer/view_components/blob/main/app/lib/primer/classify.rb) to Primer CSS classes, with any remaining options passed to Rails' [`content_tag`](https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-content_tag).
+  # Under the hood, system arguments are [mapped](https://github.com/primer/view_components/blob/main/lib/primer/classify.rb) to Primer CSS classes, with any remaining options passed to Rails' [`content_tag`](https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-content_tag).
   #
   # ## Responsive values
   #
@@ -85,7 +85,7 @@ module Primer
     #
     # | Name | Type | Description |
     # | :- | :- | :- |
-    # | `clearfix` | Boolean | Wether to assign the `clearfix` class. |
+    # | `clearfix` | Boolean | Whether to assign the `clearfix` class. |
     # | `col` | Integer | Number of columns. <%= one_of(Primer::Classify::Utilities.mappings(:col)) %> |
     # | `container` | Symbol | Size of the container. <%= one_of(Primer::Classify::Utilities.mappings(:container)) %> |
     #

data/app/components/primer/beta/auto_complete/auto_complete.html.erb

@@ -1,14 +1,24 @@
 <%= render Primer::BaseComponent.new(**@system_arguments) do %>
-  <label for="<%= @input_id %>">
+  <label for="<%= @input_id %>" class="<%= @label_classes %>">
     <% if @is_label_visible %>
       <%= @label_text %>
     <% else %>
       <span class="sr-only"><%= @label_text %></span>
     <% end %>
-    <% if icon.present? %>
-      <%= icon %>
-    <% end %>
   </label>
-  <input id="<%= @input_id %>" name="<%= @input_id %>" type="text" class="form-control" autocomplete="off">
-  <%= results %>
+  <span class="autocomplete-body">
+    <% if @with_icon %>
+      <div class="form-control autocomplete-embedded-icon-wrap">
+        <%= render Primer::OcticonComponent.new(:search) %>
+    <% end %>
+    <%= input %>
+    <% if @is_clearable %>
+      <button id="<%= @input_id %>-clear" class="btn-octicon" aria-label="Clear"><%= primer_octicon "x" %></button>
+    <% end %>
+    <% if @with_icon %>
+      </div>
+    <% end %>
+    <%= results %>
+  </span>
+  <div id="<%= @list_id %>-feedback" class="sr-only"></div>
 <% end %>

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

@@ -13,10 +13,7 @@ module Primer
     #   be used unless there is compelling reason not to. A placeholder is not a label.
     class AutoComplete < Primer::Component
       status :beta
-
-      # 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 %>
@@ -32,14 +29,79 @@ module Primer
         Primer::BaseComponent.new(**system_arguments)
       }
 
+      # Customizable input used to search for results.
+      # It is preferred to use this slot sparingly - it will be created by default if not explicity added.
+      #
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :input, lambda { |**system_arguments|
+        sanitized_args = deny_tag_argument(**system_arguments)
+        sanitized_args = deny_single_argument(:autofocus, "autofocus is not allowed for accessibility reasons. See https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus#accessibility_considerations for more information.", **sanitized_args)
+        deny_aria_key(
+          :label,
+          "instead of `aria-label`, include `label_text` and set `is_label_visible` to `false` on the component initializer.",
+          **sanitized_args
+        )
+        deny_single_argument(
+          :id,
+          "`id` will always be set to @input_id.",
+          **sanitized_args
+        )
+        deny_single_argument(
+          :name,
+          "Set @input_name on the component initializer instead with `input_name`.",
+          **sanitized_args
+        )
+        sanitized_args[:id] = @input_id
+        sanitized_args[:name] = @input_name
+        sanitized_args[:tag] = :input
+        sanitized_args[:autocomplete] = "off"
+
+        sanitized_args[:type] = :text
+        sanitized_args[:classes] = class_names(
+          "form-control",
+          sanitized_args[:classes]
+        )
+
+        Primer::BaseComponent.new(**sanitized_args)
+      }
+
       # @example Default
-      #   <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input-1", list_id: "fruits-popup-1", position: :relative)) %>
+      #   @description
+      #     Labels are stacked by default.
+      #   @code
+      #     <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--default", list_id: "fruits-popup--default")) %>
+      #
+      # @example With inline label
+      #   @description
+      #     Labels can be inline by setting `is_label_inline: true`. However, labels will always become stacked on smaller screen sizes.
+      #   @code
+      #     <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", is_label_inline: true, input_id: "fruits-input--inline-label", list_id: "fruits-popup--inline-label")) %>
+      #
+      # @example With non-visible label
+      #   @description
+      #     A non-visible label may be rendered with `is_label_visible: false`, but it is highly discouraged. See <%= link_to_accessibility %>.
+      #   @code
+      #     <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--non-visible-label", list_id: "fruits-popup--non-visible-label", is_label_visible: false)) %>
+      #
+      # @example With icon
+      #   @description
+      #     To display a search icon, set `with_icon` to `true`.
+      #   @code
+      #     <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", list_id: "fruits-popup--icon", input_id: "fruits-input--icon", with_icon: true)) %>
+      #
+      # @example With icon and non-visible label
+      #   <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", list_id: "fruits-popup--icon-no-label", input_id: "fruits-input--icon-no-label", with_icon: true, is_label_visible: false)) %>
       #
-      # @example With Non-Visible Label
-      #   <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input-2", list_id: "fruits-popup-2", is_label_visible: false, position: :relative)) %>
+      # @example With clear button
+      #   <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--clear", list_id: "fruits-popup--clear", is_clearable: true)) %>
       #
-      # @example With Custom Classes for the Results
-      #   <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input-3", list_id: "fruits-popup-3", position: :relative)) do |c| %>
+      # @example With custom classes for the input
+      #   <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--custom-input", list_id: "fruits-popup--custom-input")) do |c| %>
+      #     <% c.input(classes: "custom-class") %>
+      #   <% end %>
+      #
+      # @example With custom classes for the results
+      #   <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--custom-results", list_id: "fruits-popup--custom-results")) do |c| %>
       #     <% c.results(classes: "custom-class") do %>
       #       <%= render(Primer::Beta::AutoComplete::Item.new(selected: true, value: "apple")) do |c| %>
       #         Apple
@@ -50,36 +112,36 @@ module Primer
       #     <% end %>
       #   <% end %>
       #
-      # @example With Icon
-      #   <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", list_id: "fruits-popup-4", input_id: "fruits-input-4", position: :relative)) do |c| %>
-      #     <% c.icon(icon: :search) %>
-      #   <% end %>
-      #
-      # @example With Icon and Non-Visible Label
-      #   <%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", list_id: "fruits-popup-5", input_id: "fruits-input-5", is_label_visible: false, position: :relative)) do |c| %>
-      #     <% c.icon(icon: :search) %>
-      #   <% end %>
       # @param label_text [String] The label of the input.
       # @param src [String] The route to query.
       # @param input_id [String] Id of the input element.
+      # @param input_name [String] Optional name of the input element, defaults to `input_id` when not set.
       # @param list_id [String] Id of the list element.
+      # @param with_icon [Boolean] Controls if a search icon is visible, defaults to `false`.
       # @param is_label_visible [Boolean] Controls if the label is visible. If `false`, screen reader only text will be added.
+      # @param is_clearable [Boolean] Adds optional clear button.
+      # @param is_label_inline [Boolean] Controls if the label is inline. On smaller screens, label will always become stacked.
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-      def initialize(label_text:, src:, list_id:, input_id:, is_label_visible: true, **system_arguments)
+      def initialize(label_text:, src:, list_id:, input_id:, input_name: nil, is_label_visible: true, is_label_inline: false, with_icon: false, is_clearable: false, **system_arguments)
         @label_text = label_text
         @list_id = list_id
         @input_id = input_id
+        @input_name = input_name || input_id
         @is_label_visible = is_label_visible
+        @with_icon = with_icon
+        @is_clearable = is_clearable
 
+        @label_classes = is_label_inline ? "autocomplete-label-inline" : "autocomplete-label-stacked"
         @system_arguments = deny_tag_argument(**system_arguments)
         @system_arguments[:tag] = "auto-complete"
         @system_arguments[:src] = src
         @system_arguments[:for] = list_id
       end
 
-      # add `results` without needing to explicitly call them in the view
+      # add `input` and `results` without needing to explicitly call them in the view
       def before_render
         results(classes: "") unless results
+        input(classes: "") unless input
       end
     end
   end

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

@@ -92,6 +92,7 @@ module Primer
           @system_arguments[:tag] = system_arguments[:tag] || :span
           @system_arguments[:classes] = class_names(
             "Truncate-text",
+            system_arguments[:classes],
             "Truncate-text--primary": priority,
             "Truncate-text--expandable": expandable
           )

data/app/components/primer/button_component.html.erb

@@ -1,3 +1,4 @@
 <%= render Primer::BaseButton.new(**@system_arguments) do -%>
   <%= leading_visual %><%= trimmed_content %><%= trailing_visual %><%= primer_octicon("triangle-down", ml: 2, mr: -1) if @dropdown %>
+  <%= tooltip %>
 <% end -%>

data/app/components/primer/button_component.rb

@@ -56,6 +56,23 @@ module Primer
     }
     alias counter trailing_visual_counter # remove alias when all buttons are migrated to new slot names
 
+    # `Tooltip` that appears on mouse hover or keyboard focus over the button. Use tooltips sparingly and as a last resort.
+    # **Important:** This tooltip defaults to `type: :description`. In a few scenarios, `type: :label` may be more appropriate.
+    # Consult the <%= link_to_component(Primer::Alpha::Tooltip) %> documentation for more information.
+    #
+    # @param type [Symbol] (:description) <%= one_of(Primer::Alpha::Tooltip::TYPE_OPTIONS) %>
+    # @param system_arguments [Hash] Same arguments as <%= link_to_component(Primer::Alpha::Tooltip) %>.
+    renders_one :tooltip, lambda { |**system_arguments|
+      raise ArgumentError, "Buttons with a tooltip must have a unique `id` set on the `Button`." if @id.blank? && !Rails.env.production?
+
+      @system_arguments = system_arguments
+
+      @system_arguments[:for_id] = @id
+      @system_arguments[:type] ||= :description
+
+      Primer::Alpha::Tooltip.new(**@system_arguments)
+    }
+
     # @example Schemes
     #   <%= render(Primer::ButtonComponent.new) { "Default" } %>
     #   <%= render(Primer::ButtonComponent.new(scheme: :primary)) { "Primary" } %>
@@ -96,6 +113,15 @@ module Primer
     #     Button
     #   <% end %>
     #
+    # @example With tooltip
+    #   @description
+    #     Use tooltips sparingly and as a last resort. Consult the <%= link_to_component(Primer::Alpha::Tooltip) %> documentation for more information.
+    #   @code
+    #     <%= render(Primer::ButtonComponent.new(id: "button-with-tooltip")) do |c| %>
+    #       <% c.tooltip(text: "Tooltip text") %>
+    #       Button
+    #     <% end %>
+    #
     # @param scheme [Symbol] <%= one_of(Primer::ButtonComponent::SCHEME_OPTIONS) %>
     # @param variant [Symbol] DEPRECATED. <%= one_of(Primer::ButtonComponent::SIZE_OPTIONS) %>
     # @param size [Symbol] <%= one_of(Primer::ButtonComponent::SIZE_OPTIONS) %>
@@ -118,6 +144,9 @@ module Primer
       @dropdown = dropdown
 
       @system_arguments = system_arguments
+
+      @id = @system_arguments[:id]
+
       @system_arguments[:classes] = class_names(
         system_arguments[:classes],
         SCHEME_MAPPINGS[fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)],

data/app/components/primer/component.rb

@@ -102,10 +102,17 @@ module Primer
     def deny_aria_label(tag:, arguments:)
       return arguments.except!(:skip_aria_label_check) if arguments[:skip_aria_label_check]
       return if arguments[:role]
-      return unless aria(:label, arguments)
       return unless INVALID_ARIA_LABEL_TAGS.include?(tag)
 
-      raise ArgumentError, "Don't use `aria-label` on `#{tag}` elements. See https://www.tpgi.com/short-note-on-aria-label-aria-labelledby-and-aria-describedby/" if should_raise_aria_error?
+      deny_aria_key(
+        :label,
+        "Don't use `aria-label` on `#{tag}` elements. See https://www.tpgi.com/short-note-on-aria-label-aria-labelledby-and-aria-describedby/",
+        **arguments
+      )
+    end
+
+    def deny_aria_key(key, help_text, **arguments)
+      raise ArgumentError, help_text if should_raise_aria_error? && aria(key, arguments)
     end
 
     def deny_tag_argument(**arguments)

data/app/components/primer/details_component.rb

@@ -49,7 +49,7 @@ module Primer
     #   <% 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 reset [Boolean] Defaults 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 %>
     def initialize(overlay: NO_OVERLAY, reset: false, **system_arguments)
       @system_arguments = deny_tag_argument(**system_arguments)

data/app/components/primer/icon_button.rb

@@ -6,7 +6,7 @@ module Primer
   # @accessibility
   #   `IconButton` requires an `aria-label`, which will provide assistive technologies with an accessible label.
   #   The `aria-label` should describe the action to be invoked rather than the icon itself. For instance,
-  #   if your `IconButton` renders a magnifying glass icon and invokves a search action, the `aria-label` should be
+  #   if your `IconButton` renders a magnifying glass icon and invokes a search action, the `aria-label` should be
   #   `"Search"` instead of `"Magnifying glass"`.
   #   [Learn more about best functional image practices (WAI Images)](https://www.w3.org/WAI/tutorials/images/functional)
   class IconButton < Primer::Component