primer_view_components 0.0.68 → 0.0.69

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

@@ -0,0 +1,377 @@
+import type {AnchorAlignment, AnchorSide} from '@primer/behaviors'
+import {getAnchoredPosition} from '@primer/behaviors'
+
+const TOOLTIP_OPEN_CLASS = 'tooltip-open'
+
+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
+      }
+      
+      :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-se):before,
+      :host(.tooltip-sw):before {
+        right: 50%;
+        bottom: 100%;
+        margin-right: -6px;
+        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%;
+        right: 50%;
+        margin-right: -6px;
+        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 {
+        right: auto
+      }
+      
+      :host(.tooltip-sw):before,
+      :host(.tooltip-nw):before {
+        right: 0;
+        margin-right: 6px
+      }
+      
+      :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/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/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

data/app/components/primer/markdown.rb

@@ -93,7 +93,7 @@ module Primer
     #     <ol>
     #       <li>Michael Jackson</li>
     #       <li>Michael Bolton</li>
-    #       <li>Michael Buble</li>
+    #       <li>Michael Bublé</li>
     #     </ol>
     #
     #     <p>And an unordered task list:</p>

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

@@ -5,3 +5,4 @@ import './time_ago_component';
 import './local_time';
 import './image_crop';
 import './dropdown';
+import './alpha/tooltip';

data/app/components/primer/primer.js

@@ -5,3 +5,4 @@ import './time_ago_component';
 import './local_time';
 import './image_crop';
 import './dropdown';
+import './alpha/tooltip';

data/app/components/primer/primer.ts

@@ -5,3 +5,4 @@ import './time_ago_component'
 import './local_time'
 import './image_crop'
 import './dropdown'
+import './alpha/tooltip'

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

@@ -1,5 +1,5 @@
 <%= render Primer::BaseComponent.new(**@system_arguments) do %>
   <%= heading %>
-  <%= actions %>
   <%= description %>
+  <%= actions %>
 <% end %>

data/app/components/primer/subhead_component.rb

@@ -4,7 +4,7 @@ module Primer
   # Use `Subhead` as the start of a section. The `:heading` slot will render an `<h2>` font-sized text.
   #
   # - Optionally set the `:description` slot to render a short description and the `:actions` slot for a related action.
-  # - Use a succint, one-line description for the `:description` slot. For longer descriptions, omit the description slot and render a paragraph below the `Subhead`.
+  # - Use a succinct, one-line description for the `:description` slot. For longer descriptions, omit the description slot and render a paragraph below the `Subhead`.
   # - Use the actions slot to render a related action to the right of the heading. Use <%= link_to_component(Primer::ButtonComponent) %> or <%= link_to_component(Primer::LinkComponent) %>.
   #
   # @accessibility

data/lib/primer/classify/utilities.yml

@@ -39,6 +39,10 @@
   - color-fg-severe
   :danger:
   - color-fg-danger
+  :open:
+  - color-fg-open
+  :closed:
+  - color-fg-closed
   :done:
   - color-fg-done
   :sponsors:
@@ -78,6 +82,14 @@
   - color-bg-danger
   :danger_emphasis:
   - color-bg-danger-emphasis
+  :open:
+  - color-bg-open
+  :open_emphasis:
+  - color-bg-open-emphasis
+  :closed:
+  - color-bg-closed
+  :closed_emphasis:
+  - color-bg-closed-emphasis
   :done:
   - color-bg-done
   :done_emphasis:
@@ -113,6 +125,14 @@
   - color-border-danger
   :danger_emphasis:
   - color-border-danger-emphasis
+  :open:
+  - color-border-open
+  :open_emphasis:
+  - color-border-open-emphasis
+  :closed:
+  - color-border-closed
+  :closed_emphasis:
+  - color-border-closed-emphasis
   :done:
   - color-border-done
   :done_emphasis:

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

@@ -15,7 +15,7 @@ module ERBLint
         constant: "TAG_OPTIONS"
       ).freeze
 
-      # CloseButton component has preference when this class is seen in conjuction with `btn`.
+      # CloseButton component has preference when this class is seen in conjunction with `btn`.
       DISALLOWED_CLASSES = %w[close-button].freeze
       CLASSES = %w[btn btn-link].freeze
       MESSAGE = "We are migrating buttons to use [Primer::ButtonComponent](https://primer.style/view-components/components/button), please try to use that instead of raw HTML."

data/lib/primer/view_components/version.rb

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

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

@@ -207,7 +207,7 @@ module RuboCop
           return node.source unless node.type == :str
           return ":#{node.value}" unless node.value.include?("-")
 
-          # If the icon contains `-` we need to cast the string as a symbole
+          # If the icon contains `-` we need to cast the string as a symbol
           # E.g: `arrow-down` becomes `:"arrow-down"`
           ":#{node.source}"
         end

data/lib/tasks/docs.rake

@@ -82,7 +82,8 @@ namespace :docs do
       Primer::Alpha::UnderlineNav,
       Primer::Alpha::UnderlinePanels,
       Primer::Alpha::TabNav,
-      Primer::Alpha::TabPanels
+      Primer::Alpha::TabPanels,
+      Primer::Alpha::Tooltip
     ]
 
     js_components = [
@@ -94,7 +95,8 @@ namespace :docs do
       Primer::TabContainerComponent,
       Primer::TimeAgoComponent,
       Primer::Alpha::UnderlinePanels,
-      Primer::Alpha::TabPanels
+      Primer::Alpha::TabPanels,
+      Primer::Alpha::Tooltip
     ]
 
     all_components = Primer::Component.descendants - [Primer::BaseComponent]
@@ -168,12 +170,12 @@ namespace :docs do
         f.puts("| Name | Type | Default | Description |")
         f.puts("| :- | :- | :- | :- |")
 
-        docummented_params = params.map(&:name)
+        documented_params = params.map(&:name)
         component_params = component.instance_method(:initialize).parameters.map { |p| p.last.to_s }
 
-        if (docummented_params & component_params).size != component_params.size
+        if (documented_params & component_params).size != component_params.size
           err = { arguments: {} }
-          (component_params - docummented_params).each do |arg|
+          (component_params - documented_params).each do |arg|
             err[:arguments][arg] = "Not documented"
           end
 

data/lib/tasks/utilities.rake

@@ -86,7 +86,7 @@ namespace :utilities do
         classname.sub!(/^[^-]+-/, "")
       end
 
-      # Change the rest from hypens to underscores
+      # Change the rest from hyphens to underscores
       classname.sub!(/-/, "_")
 
       # convert padding/margin negative values ie n7 to -7

data/static/arguments.yml

@@ -95,6 +95,30 @@
     type: Hash
     default: N/A
     description: "[System arguments](/system-arguments)"
+- component: Tooltip
+  source: https://github.com/primer/view_components/tree/main/app/components/primer/alpha/tooltip.rb
+  parameters:
+  - name: for_id
+    type: String
+    default: N/A
+    description: The ID of the element that the tooltip should be attached to.
+  - name: type
+    type: Symbol
+    default: N/A
+    description: One of `:description` and `:label`.
+  - name: direction
+    type: Symbol
+    default: "`:s`"
+    description: One of `:e`, `:n`, `:ne`, `:nw`, `:s`, `:se`, `:sw`, or `:w`.
+  - name: text
+    type: String
+    default: N/A
+    description: The text content of the tooltip. This should be brief and no longer
+      than a sentence.
+  - name: system_arguments
+    type: Hash
+    default: N/A
+    description: "[System arguments](/system-arguments)"
 - component: UnderlineNav
   source: https://github.com/primer/view_components/tree/main/app/components/primer/alpha/underline_nav.rb
   parameters:
@@ -453,7 +477,7 @@
   - name: reset
     type: Boolean
     default: "`false`"
-    description: Defatuls to false. If set to true, it will remove the default caret
+    description: Defaults to false. If set to true, it will remove the default caret
       and remove style from the summary element
   - name: system_arguments
     type: Hash

data/static/audited_at.json

@@ -6,6 +6,7 @@
   "Primer::Alpha::Layout::Sidebar": "",
   "Primer::Alpha::TabNav": "",
   "Primer::Alpha::TabPanels": "",
+  "Primer::Alpha::Tooltip": "",
   "Primer::Alpha::UnderlineNav": "",
   "Primer::Alpha::UnderlinePanels": "",
   "Primer::BaseButton": "",

data/static/classes.yml

@@ -171,6 +171,7 @@
 - ".left-0"
 - ".lh-0"
 - ".list-style-none"
+- ".m-2"
 - ".markdown-body"
 - ".mb-0"
 - ".mb-2"

data/static/constants.json

@@ -138,6 +138,24 @@
       "div"
     ]
   },
+  "Primer::Alpha::Tooltip": {
+    "DIRECTION_DEFAULT": "s",
+    "DIRECTION_OPTIONS": [
+      "s",
+      "n",
+      "e",
+      "w",
+      "ne",
+      "nw",
+      "se",
+      "sw"
+    ],
+    "TYPE_FALLBACK": "description",
+    "TYPE_OPTIONS": [
+      "label",
+      "description"
+    ]
+  },
   "Primer::Alpha::UnderlineNav": {
     "BODY_TAG_DEFAULT": "ul",
     "TAG_DEFAULT": "nav",

data/static/statuses.json

@@ -6,6 +6,7 @@
   "Primer::Alpha::Layout::Sidebar": "alpha",
   "Primer::Alpha::TabNav": "alpha",
   "Primer::Alpha::TabPanels": "alpha",
+  "Primer::Alpha::Tooltip": "alpha",
   "Primer::Alpha::UnderlineNav": "alpha",
   "Primer::Alpha::UnderlinePanels": "alpha",
   "Primer::BaseButton": "beta",