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

@@ -10,6 +10,7 @@ import {
   AlphaTransition,
   MaxHeightTransition,
   MoveTransition,
+  Tooltip,
 } from '@cfpb/cfpb-design-system';
 import Tabs from './tabs.js';
 import redirectBanner from './redirect-banner.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,40 @@
+---
+title: Tooltips
+collection_name: pages
+layout: variation
+section: components
+status: Beta
+description: A tooltip is a short descriptive message that appears when a user
+  hovers or focuses on an element. They display helpful but non-critical
+  information and are useful in space-constrained user interfaces.
+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>
+
+    variation_group_name: Standard tooltip
+    variation_group_description: ""
+guidelines: Tooltips should be activated by hovering or focusing over a help
+  (question mark) icon that is next to text that requires additional clarity.
+  They contain standard size body text and an optional `h3` heading.
+eyebrow: Components
+behavior: Pressing the `esc` key should dismiss all 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: >-
+  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' guidelines](https://designsystem.digital.gov/components/tooltip/accessibility-tests/).
+related_items: ""
+---

packages/cfpb-design-system/package.json

@@ -20,5 +20,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,6 @@
+/* ==========================================================================
+   Design System
+   Tooltips
+   ========================================================================== */
+
+export { Tooltip } from './tooltip.js';

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

@@ -0,0 +1,81 @@
+/* ==========================================================================
+   Tooltip Organism
+   ========================================================================== */
+
+import tippy from 'tippy.js';
+
+import { instantiateAll } from '../../utilities';
+
+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) {
+  // Internal vars.
+  const tooltipContent = element.getAttribute('data-tooltip');
+
+  /**
+   * Set up and create the multiselect.
+   * @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.addEventListener('keydown', onKeyDown);
+              },
+              onHide() {
+                document.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,27 @@
+@use 'sass:math';
+@use '@cfpb/cfpb-design-system/src/abstracts' as *;
+@import 'tippy.js/dist/tippy.css';
+@import '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;
+  }
+}

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

@@ -14,6 +14,7 @@ export * from './components/cfpb-layout';
 export * from './components/cfpb-notifications';
 export * from './components/cfpb-pagination';
 export * from './components/cfpb-tables';
+export * from './components/cfpb-tooltips';
 export * from './components/cfpb-typography';
 
 export * from './utilities';

yarn.lock

@@ -1579,6 +1579,11 @@
   resolved "https://registry.yarnpkg.com/@pkgjs/parseargs/-/parseargs-0.11.0.tgz#a77ea742fab25775145434eb1d2328cf5013ac33"
   integrity sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==
 
+"@popperjs/core@^2.9.0":
+  version "2.11.8"
+  resolved "https://registry.yarnpkg.com/@popperjs/core/-/core-2.11.8.tgz#6b79032e760a0899cd4204710beede972a3a185f"
+  integrity sha512-P1st0aksCrn9sGZhp8GMYwBnQsbvAWsZAX44oXNNvLHGqAOcoVxmjZiohstwQ7SqKnbR47akdNi+uleWD8+g6A==
+
 "@puppeteer/[email protected]":
   version "2.3.0"
   resolved "https://registry.yarnpkg.com/@puppeteer/browsers/-/browsers-2.3.0.tgz#791ea7d80450fea24eb19fb1d70c367ad4e08cae"
@@ -11131,16 +11136,7 @@ string-length@^4.0.1:
     char-regex "^1.0.2"
     strip-ansi "^6.0.0"
 
-"string-width-cjs@npm:string-width@^4.2.0":
-  version "4.2.3"
-  resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
-  integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==
-  dependencies:
-    emoji-regex "^8.0.0"
-    is-fullwidth-code-point "^3.0.0"
-    strip-ansi "^6.0.1"
-
-"string-width@^1.0.2 || 2 || 3 || 4", string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3:
+"string-width-cjs@npm:string-width@^4.2.0", "string-width@^1.0.2 || 2 || 3 || 4", string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3:
   version "4.2.3"
   resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
   integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==
@@ -11245,7 +11241,7 @@ stringify-entities@^3.0.1:
     character-entities-legacy "^1.0.0"
     xtend "^4.0.0"
 
-"strip-ansi-cjs@npm:strip-ansi@^6.0.1":
+"strip-ansi-cjs@npm:strip-ansi@^6.0.1", strip-ansi@^6.0.0, strip-ansi@^6.0.1:
   version "6.0.1"
   resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9"
   integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==
@@ -11266,13 +11262,6 @@ strip-ansi@^5.1.0:
   dependencies:
     ansi-regex "^4.1.0"
 
-strip-ansi@^6.0.0, strip-ansi@^6.0.1:
-  version "6.0.1"
-  resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9"
-  integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==
-  dependencies:
-    ansi-regex "^5.0.1"
-
 strip-ansi@^7.0.1, strip-ansi@^7.1.0:
   version "7.1.0"
   resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-7.1.0.tgz#d5b6568ca689d8561370b0707685d22434faff45"
@@ -11629,6 +11618,13 @@ tinycolor2@^1.4.1:
   resolved "https://registry.yarnpkg.com/tinycolor2/-/tinycolor2-1.6.0.tgz#f98007460169b0263b97072c5ae92484ce02d09e"
   integrity sha512-XPaBkWQJdsf3pLKJV9p4qN/S+fm2Oj8AIPo1BTUhg5oxkvm9+SVEGFdhyOz7tTdUTfvxMiAs4sp6/eZO2Ew+pw==
 
+tippy.js@^6.3.7:
+  version "6.3.7"
+  resolved "https://registry.yarnpkg.com/tippy.js/-/tippy.js-6.3.7.tgz#8ccfb651d642010ed9a32ff29b0e9e19c5b8c61c"
+  integrity sha512-E1d3oP2emgJ9dRQZdf3Kkn0qJgI6ZLpyS5z6ZkY1DF3kaQaBsGZsndEpHwx+eC+tYM41HaSNvNtLx8tU57FzTQ==
+  dependencies:
+    "@popperjs/core" "^2.9.0"
+
 tldts-core@^6.1.38:
   version "6.1.38"
   resolved "https://registry.yarnpkg.com/tldts-core/-/tldts-core-6.1.38.tgz#e8064921dc65a2c672e95db004c2f5bb0113bad0"
@@ -12495,7 +12491,7 @@ wordwrap@^1.0.0:
   resolved "https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb"
   integrity sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==
 
-"wrap-ansi-cjs@npm:wrap-ansi@^7.0.0":
+"wrap-ansi-cjs@npm:wrap-ansi@^7.0.0", wrap-ansi@^7.0.0:
   version "7.0.0"
   resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43"
   integrity sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==
@@ -12513,15 +12509,6 @@ wrap-ansi@^6.0.1, wrap-ansi@^6.2.0:
     string-width "^4.1.0"
     strip-ansi "^6.0.0"
 
-wrap-ansi@^7.0.0:
-  version "7.0.0"
-  resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43"
-  integrity sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==
-  dependencies:
-    ansi-styles "^4.0.0"
-    string-width "^4.1.0"
-    strip-ansi "^6.0.0"
-
 wrap-ansi@^8.1.0:
   version "8.1.0"
   resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-8.1.0.tgz#56dc22368ee570face1b49819975d9b9a5ead214"