primer_view_components 0.0.68 → 0.0.69

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

@@ -0,0 +1,24 @@
+declare type Direction = 'n' | 's' | 'e' | 'w' | 'ne' | 'se' | 'nw' | 'sw';
+declare class TooltipElement extends HTMLElement {
+    #private;
+    styles(): string;
+    get htmlFor(): string;
+    set htmlFor(value: string);
+    get type(): 'description' | 'label';
+    set type(value: 'description' | 'label');
+    get direction(): Direction;
+    set direction(value: Direction);
+    get control(): HTMLElement | null;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    handleEvent(event: Event): void;
+    static observedAttributes: string[];
+    attributeChangedCallback(name: string): void;
+}
+declare global {
+    interface Window {
+        TooltipElement: typeof TooltipElement;
+    }
+}
+export {};

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

@@ -0,0 +1,381 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, privateMap, value) {
+    if (!privateMap.has(receiver)) {
+        throw new TypeError("attempted to set private field on non-instance");
+    }
+    privateMap.set(receiver, value);
+    return value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, privateMap) {
+    if (!privateMap.has(receiver)) {
+        throw new TypeError("attempted to get private field on non-instance");
+    }
+    return privateMap.get(receiver);
+};
+var _abortController, _align, _side, _allowUpdatePosition;
+import { getAnchoredPosition } from '@primer/behaviors';
+const TOOLTIP_OPEN_CLASS = 'tooltip-open';
+const DIRECTION_CLASSES = [
+    'tooltip-n',
+    'tooltip-s',
+    'tooltip-e',
+    'tooltip-w',
+    'tooltip-ne',
+    'tooltip-se',
+    'tooltip-nw',
+    'tooltip-sw'
+];
+class TooltipElement extends HTMLElement {
+    constructor() {
+        super();
+        _abortController.set(this, void 0);
+        _align.set(this, 'center');
+        _side.set(this, 'outside-bottom');
+        _allowUpdatePosition.set(this, false);
+        const shadow = this.attachShadow({ mode: 'open' });
+        shadow.innerHTML = `
+      <style>
+        ${this.styles()}
+      </style>
+      <slot></slot>
+    `;
+    }
+    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)
+      }
+    `;
+    }
+    get htmlFor() {
+        return this.getAttribute('for') || '';
+    }
+    set htmlFor(value) {
+        this.setAttribute('for', value);
+    }
+    get type() {
+        const type = this.getAttribute('data-type');
+        return type === 'label' ? 'label' : 'description';
+    }
+    set type(value) {
+        this.setAttribute('data-type', value);
+    }
+    get direction() {
+        return (this.getAttribute('data-direction') || 's');
+    }
+    set direction(value) {
+        this.setAttribute('data-direction', value);
+    }
+    get control() {
+        return this.ownerDocument.getElementById(this.htmlFor);
+    }
+    connectedCallback() {
+        var _a;
+        this.hidden = true;
+        __classPrivateFieldSet(this, _allowUpdatePosition, true);
+        if (!this.id) {
+            this.id = `tooltip-${Date.now()}-${(Math.random() * 10000).toFixed(0)}`;
+        }
+        if (!this.control)
+            return;
+        this.setAttribute('role', 'tooltip');
+        (_a = __classPrivateFieldGet(this, _abortController)) === null || _a === void 0 ? void 0 : _a.abort();
+        __classPrivateFieldSet(this, _abortController, new AbortController());
+        const { signal } = __classPrivateFieldGet(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() {
+        var _a;
+        (_a = __classPrivateFieldGet(this, _abortController)) === null || _a === void 0 ? void 0 : _a.abort();
+    }
+    handleEvent(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.relatedTarget !== this.control &&
+            event.relatedTarget !== this) {
+            this.hidden = true;
+        }
+        else if (event.type === 'keydown' && event.key === 'Escape' && !this.hidden) {
+            this.hidden = true;
+        }
+    }
+    attributeChangedCallback(name) {
+        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(this.tagName)) {
+                    if (tooltip !== this)
+                        tooltip.hidden = true;
+                }
+                this..call(this);
+            }
+        }
+        else if (name === 'data-direction') {
+            this.classList.remove(...DIRECTION_CLASSES);
+            const direction = this.direction;
+            if (direction === 'n') {
+                __classPrivateFieldSet(this, _align, 'center');
+                __classPrivateFieldSet(this, _side, 'outside-top');
+            }
+            else if (direction === 'ne') {
+                __classPrivateFieldSet(this, _align, 'start');
+                __classPrivateFieldSet(this, _side, 'outside-top');
+            }
+            else if (direction === 'e') {
+                __classPrivateFieldSet(this, _align, 'center');
+                __classPrivateFieldSet(this, _side, 'outside-right');
+            }
+            else if (direction === 'se') {
+                __classPrivateFieldSet(this, _align, 'start');
+                __classPrivateFieldSet(this, _side, 'outside-bottom');
+            }
+            else if (direction === 's') {
+                __classPrivateFieldSet(this, _align, 'center');
+                __classPrivateFieldSet(this, _side, 'outside-bottom');
+            }
+            else if (direction === 'sw') {
+                __classPrivateFieldSet(this, _align, 'end');
+                __classPrivateFieldSet(this, _side, 'outside-bottom');
+            }
+            else if (direction === 'w') {
+                __classPrivateFieldSet(this, _align, 'center');
+                __classPrivateFieldSet(this, _side, 'outside-left');
+            }
+            else if (direction === 'nw') {
+                __classPrivateFieldSet(this, _align, 'end');
+                __classPrivateFieldSet(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
+    (anchorSide) {
+        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';
+        }
+    }
+    () {
+        if (!this.control)
+            return;
+        if (!__classPrivateFieldGet(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: __classPrivateFieldGet(this, _side),
+            align: __classPrivateFieldGet(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 = 's';
+        const align = this..call(this, 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}`);
+    }
+}
+_abortController = new WeakMap(), _align = new WeakMap(), _side = new WeakMap(), _allowUpdatePosition = new WeakMap();
+TooltipElement.observedAttributes = ['data-type', 'data-direction', 'id', 'hidden'];
+if (!window.customElements.get('tool-tip')) {
+    window.TooltipElement = TooltipElement;
+    window.customElements.define('tool-tip', TooltipElement);
+}

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    # `Tooltip` only appears on mouse hover or keyboard focus and contain a label or description text.
+    # Use tooltips sparingly and as a last resort.
+    #
+    # When using a tooltip, follow the provided guidelines to avoid accessibility issues.
+    #
+    # - Tooltip text should be brief and to the point. The tooltip content must be a string.
+    # - Tooltips should contain only **non-essential text**. Tooltips can easily be missed and are not accessible on touch devices so never
+    #  use tooltips to convey critical information.
+    #
+    # @accessibility
+    #   - **Never set tooltips on static elements.** Tooltips should only be used on interactive elements like buttons or links to avoid excluding keyboard-only users
+    #   and screen reader users.
+    #   - Place `Tooltip` adjacent after its trigger element in the DOM. This allows screen reader users to navigate to and copy the tooltip
+    #   content.
+    #   ### Which `type` should I set?
+    #   Setting `:description` establishes an `aria-describedby` relationship, while `:label` establishes an `aria-labelledby` relationship between the trigger element and the tooltip,
+    #
+    #   The `type` drastically changes semantics and screen reader behavior so follow these guidelines carefully:
+    #   - When there is already a visible label text on the trigger element, the tooltip is likely intended to supplement the existing text, so set `type: :description`.
+    #   The majority of tooltips will fall under this category.
+    #   - When there is no visible text on the trigger element and the tooltip content is appropriate as a label for the element, set `type: :label`.
+    #   This type is usually only appropriate for an icon-only control.
+    class Tooltip < Primer::Component
+      DIRECTION_DEFAULT = :s
+      DIRECTION_OPTIONS = [DIRECTION_DEFAULT, :n, :e, :w, :ne, :nw, :se, :sw].freeze
+
+      TYPE_FALLBACK = :description
+      TYPE_OPTIONS = [:label, :description].freeze
+      # @example As a description for an icon-only button
+      #   @description
+      #     If the tooltip content provides supplementary description, set `type: :description` to establish an `aria-describedby` relationship.
+      #     The trigger element should also have a _concise_ accessible label via `aria-label`.
+      #   @code
+      #     <%= render(Primer::IconButton.new(id: "bold-button-0", icon: :bold, "aria-label": "Bold")) %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "bold-button-0", type: :description, text: "Add bold text", direction: :ne)) %>
+      # @example As a label for an icon-only button
+      #   @description
+      #     If the tooltip labels the icon-only button, set `type: :label`. This tooltip content becomes the accessible name for the button.
+      #   @code
+      #     <%= render(Primer::ButtonComponent.new(id: "like-button")) { "👍" } %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "like-button", type: :label, text: "Like", direction: :n)) %>
+      #
+      # @example As a description for a button with visible label
+      #   @description
+      #     If the button already has visible label text, the tooltip content is likely supplementary so set `type: :description`.
+      #   @code
+      #     <%= render(Primer::ButtonComponent.new(id: "save-button", scheme: :primary)) { "Save" } %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "save-button", type: :description, text: "This will immediately impact all organization members", direction: :ne)) %>
+      # @example With direction
+      #   @description
+      #     Set direction of tooltip with `direction`. The tooltip is responsive and will automatically adjust direction to avoid cutting off.
+      #   @code
+      #     <%= render(Primer::ButtonComponent.new(id: "North", m: 2)) { "North" } %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "North", type: :description, text: "This is a North-facing tooltip, and is responsive.", direction: :n)) %>
+      #     <%= render(Primer::ButtonComponent.new(id: "South", m: 2)) { "South" } %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "South", type: :description, text: "This is a South-facing tooltip and is responsive.", direction: :s)) %>
+      #     <%= render(Primer::ButtonComponent.new(id: "East", m: 2)) { "East" } %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "East", type: :description, text: "This is a East-facing tooltip and is responsive.", direction: :e)) %>
+      #     <%= render(Primer::ButtonComponent.new(id: "West", m: 2)) { "West" } %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "West", type: :description, text: "This is a West-facing tooltip and is responsive.", direction: :w)) %>
+      #     <%= render(Primer::ButtonComponent.new(id: "Northeast", m: 2)) { "Northeast" } %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "Northeast", type: :description, text: "This is a Northeast-facing tooltip and is responsive.", direction: :ne)) %>
+      #     <%= render(Primer::ButtonComponent.new(id: "Southeast", m: 2)) { "Southeast" } %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "Southeast", type: :description, text: "This is a Southeast-facing tooltip and is responsive.", direction: :se)) %>
+      #     <%= render(Primer::ButtonComponent.new(id: "Northwest", m: 2)) { "Northwest" } %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "Northwest", type: :description, text: "This is a Northwest-facing tooltip and is responsive.", direction: :nw)) %>
+      #     <%= render(Primer::ButtonComponent.new(id: "Southwest", m: 2)) { "Southwest" } %>
+      #     <%= render(Primer::Alpha::Tooltip.new(for_id: "Southwest", type: :description, text: "This is a Southwest-facing tooltip and is responsive.", direction: :sw)) %>
+      # @param for_id [String] The ID of the element that the tooltip should be attached to.
+      # @param type [Symbol] <%= one_of(Primer::Alpha::Tooltip::TYPE_OPTIONS) %>
+      # @param direction [Symbol] <%= one_of(Primer::Alpha::Tooltip::DIRECTION_OPTIONS) %>
+      # @param text [String] The text content of the tooltip. This should be brief and no longer than a sentence.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(type:, for_id:, text:, direction: DIRECTION_DEFAULT, **system_arguments)
+        raise TypeError, "tooltip text must be a string" unless text.is_a?(String)
+
+        @text = text
+        @system_arguments = system_arguments
+        @system_arguments[:hidden] = true
+        @system_arguments[:tag] = :"tool-tip"
+        @system_arguments[:for] = for_id
+        @system_arguments[:"data-direction"] = fetch_or_fallback(DIRECTION_OPTIONS, direction, DIRECTION_DEFAULT).to_s
+        @system_arguments[:"data-type"] = fetch_or_fallback(TYPE_OPTIONS, type, TYPE_FALLBACK).to_s
+      end
+
+      def call
+        render(Primer::BaseComponent.new(**@system_arguments)) { @text }
+      end
+      end
+    end
+  end