Merge pull request #2054 from cfpb/tooltips

Add new tooltip component to DS

docs/_data/side-navigation.yml

@@ -49,6 +49,7 @@ first-level:
           - page: Tags
           - page: Taglines
           - page: Text inputs
+          - page: Tooltips
         third-level: []
     nav-items: []
   - heading: Patterns

docs/assets/js/main.js

@@ -11,6 +11,7 @@ import {
   MaxHeightTransition,
   MoveTransition,
 } from '@cfpb/cfpb-design-system';
+import { Tooltip } from '@cfpb/cfpb-design-system/tooltips';
 import Tabs from './tabs.js';
 import redirectBanner from './redirect-banner.js';
 import sidebar from './sidebar.js';
@@ -37,6 +38,7 @@ SummaryMinimal.init();
 ExpandableGroup.init();
 Expandable.init();
 Multiselect.init();
+Tooltip.init();
 
 // Exporting these classes to the window so that the transition-patterns.md
 // page can use them in its code snippets.

docs/pages/tooltips.md

@@ -0,0 +1,91 @@
+---
+title: Tooltips
+collection_name: pages
+layout: variation
+section: components
+status: Beta
+description: A tooltip provides short, descriptive information when a user
+  hovers or focuses on an element. It contains helpful but non-critical
+  information and is useful in a space-constrained user interface.
+variation_groups:
+  - variations:
+      - variation_is_deprecated: false
+        variation_code_snippet: >-
+          The APR for the World Bank Platinum Credit Card is 9.7% <span
+          data-tooltip="relevant-tooltip">{% include icons/help-round.svg
+          %}</span>
+
+
+          <template id="relevant-tooltip">
+              <div class="tippy-heading">This data is accurate as of June 2023</div>
+              <div class="tippy-body">
+                  APRs change over time and are specific to the applicant. Check rates before applying.
+              </div>
+          </template>
+
+
+          <!--
+
+          Tooltips require a <template> element with an 'id' that matches the 'data-tooltip'
+
+          attribute of the tooltip's trigger element. The template can be anywhere on the page.
+
+
+          Additionally, the tooltip component must be imported independently of the rest of
+
+          the Design System using the namespace '@cfpb/cfpb-design-system/tooltips'.
+
+          For example, your project's JavaScript file might look like:
+
+
+          import {
+            Expandable,
+            ExpandableGroup,
+            Summary,
+            Multiselect,
+          } from '@cfpb/cfpb-design-system';
+
+          import { Tooltip } from '@cfpb/cfpb-design-system/tooltips';
+
+
+          Summary.init();
+
+          Expandable.init();
+
+          ExpandableGroup.init();
+
+          Multiselect.init();
+
+          Tooltip.init();
+
+
+          ...rest of your code
+
+          -->
+        variation_description: ''
+        variation_code_snippet_rendered: ''
+    variation_group_name: Standard tooltip
+    variation_group_description: ''
+guidelines: Be judicious in using tooltips and explore other design options that
+  keep content visible before choosing to use a tooltip. Only consider using a
+  tooltip for short, non-critical information in a space-constrained user
+  interface. Because a tooltip is hidden until activated, ensure content within
+  a tooltip is not essential for completing a task on the page. The tooltip
+  trigger element (usually a help icon) will be hidden for users with JavaScript
+  disabled. For more guidance, see the [USWDS tooltip
+  page](https://designsystem.digital.gov/components/tooltip/).
+eyebrow: Components
+behavior: >
+  - Activate a tooltip by hovering or focusing on a help (question mark) icon
+  situated next to text.
+
+  - Press the escape key to dismiss open tooltips.
+
+  - When a tooltip is at the edge of the user’s viewport, it should automatically reorient itself away from the edge of the screen to prevent content clipping.
+accessibility: As USWDS states, tooltips are progressive enhancements for the
+  title attribute and will display as the title attribute if the component
+  doesn’t initialize. When testing tooltips for accessibility, ensure they are
+  compliant with [USWDS tooltip accessibility
+  tests](https://designsystem.digital.gov/components/tooltip/accessibility-tests/).
+related_items: ''
+---

packages/cfpb-design-system/package.json

@@ -2,7 +2,10 @@
   "name": "@cfpb/cfpb-design-system",
   "version": "3.5.0",
   "description": "CFPB's UI framework",
-  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./tooltips": "./src/components/cfpb-tooltips/index.js"
+  },
   "author": {
     "name": "Consumer Financial Protection Bureau",
     "email": "tech@cfpb.gov",
@@ -21,5 +24,8 @@
     "url": "https://github.com/cfpb/design-system/issues"
   },
   "gitHead": "d9b9862ef0a34a0ca6f4835347ac7f202ed50e3e",
-  "type": "module"
+  "type": "module",
+  "dependencies": {
+    "tippy.js": "6.3.7"
+  }
 }

packages/cfpb-design-system/src/components/cfpb-tooltips/index.js

@@ -0,0 +1,79 @@
+/* ==========================================================================
+   Tooltip Organism
+   ========================================================================== */
+
+import tippy from 'tippy.js';
+import { instantiateAll } from '@cfpb/cfpb-design-system';
+
+import * as TooltipStyles from './tooltip.scss';
+
+const BASE_ATTRIBUTE = 'data-tooltip';
+
+/**
+ * Tooltip
+ * @class
+ * @classdesc Initializes a new Tooltip.
+ * @param {HTMLElement} element - The DOM element that should
+ *  activate the tooltip.
+ * @returns {Tooltip} An instance.
+ */
+function Tooltip(element) {
+  const tooltipContent = element.getAttribute(BASE_ATTRIBUTE);
+
+  /**
+   * Set up and create the tooltip.
+   * @returns {Tooltip} An instance.
+   */
+  function init() {
+    tippy(element, {
+      theme: 'cfpb',
+      maxWidth: 450,
+      content: function (reference) {
+        const template = reference.parentElement.querySelector(
+          `#${tooltipContent}`,
+        );
+        const container = document.createElement('div');
+        const node = document.importNode(template.content, true);
+        container.appendChild(node);
+        return container;
+      },
+      // See https://atomiks.github.io/tippyjs/v6/plugins/
+      plugins: [
+        {
+          name: 'hideOnEsc',
+          defaultValue: true,
+          fn({ hide }) {
+            /**
+             * Hide when the escape key is pressed.
+             * @param {KeyboardEvent} event - Key down event.
+             */
+            function onKeyDown(event) {
+              if (event.key === 'Escape') {
+                hide();
+              }
+            }
+            return {
+              onShow() {
+                document.body.addEventListener('keydown', onKeyDown);
+              },
+              onHide() {
+                document.body.removeEventListener('keydown', onKeyDown);
+              },
+            };
+          },
+        },
+      ],
+    });
+  }
+
+  // Attach public events.
+  this.init = init;
+
+  return this;
+}
+
+Tooltip.BASE_ATTRIBUTE = BASE_ATTRIBUTE;
+Tooltip.init = (scope) =>
+  instantiateAll(`[${Tooltip.BASE_ATTRIBUTE}]`, Tooltip, scope);
+
+export { Tooltip, TooltipStyles };

packages/cfpb-design-system/src/components/cfpb-tooltips/tooltip.scss

@@ -0,0 +1,36 @@
+@use 'sass:math';
+@use '@cfpb/cfpb-design-system/src/abstracts' as *;
+@use 'tippy.js/dist/tippy.css';
+@use 'tippy.js/dist/border.css';
+
+// Custom theme, see https://atomiks.github.io/tippyjs/v6/themes/
+.tippy-box[data-theme='cfpb'] {
+  background-color: var(--gray-5);
+  border: 1px solid var(--gray-40);
+  border-radius: 0;
+  color: var(--black);
+  padding: math.div(15px, $base-font-size-px) + rem;
+
+  .tippy-arrow {
+    color: var(--gray-5);
+  }
+
+  .tippy-heading {
+    font-weight: 500;
+    font-size: math.div(18px, $base-font-size-px) + rem;
+  }
+
+  .tippy-body {
+    font-size: math.div(16px, $base-font-size-px) + rem;
+    margin-top: math.div(15px, $base-font-size-px) + rem;
+  }
+}
+
+[data-tooltip] {
+  cursor: pointer;
+
+  // Hide tooltip trigger elements when JS isn't supported
+  .no-js & {
+    display: none;
+  }
+}