Refactor - convert initTooltips to TypeScript, add JSDoc & tests

- Fixes #9505

CHANGELOG.txt

@@ -25,6 +25,7 @@ Changelog
  * Clean up linting on legacy code and add shared util `hasOwn` in TypeScript (Loveth Omokaro)
  * Remove unnecessary box-sizing: border-box declarations in SCSS (Albina Starykova)
  * Add full support for secondary buttons with icons in the Wagtail design system - `button bicolor button--icon button-secondary` including the `button-small` variant (Seremba Patrick)
+ * Migrated `initTooltips` to TypeScript add JSDoc and unit tests (Fatuma Abdullahi)
  * Fix: Make sure workflow timeline icons are visible in high-contrast mode (Loveth Omokaro)
  * Fix: Ensure authentication forms (login, password reset) have a visible border in Windows high-contrast mode (Loveth Omokaro)
  * Fix: Ensure visual consistency between buttons and links as buttons in Windows high-contrast mode (Albina Starykova)

CONTRIBUTORS.rst

@@ -664,6 +664,7 @@ Contributors
 * Doug Harris
 * Mohammad Areeb
 * Florian Vogt
+* Fatuma Abdullahi
 
 Translators
 ===========

client/src/includes/initTooltips.test.js

@@ -0,0 +1,54 @@
+import * as tippy from 'tippy.js';
+import { initTooltips, initModernDropdown } from './initTooltips';
+
+jest.spyOn(tippy, 'default');
+
+beforeEach(() => jest.clearAllMocks());
+
+describe('initTooltips', () => {
+  it('should call the Tippy util with the [data-tippy-content] attribute', () => {
+    expect(tippy.default).not.toHaveBeenCalled();
+    initTooltips();
+    expect(tippy.default).toHaveBeenCalledWith('[data-tippy-content]', {
+      plugins: [expect.objectContaining({ name: 'hideOnEsc' })],
+    });
+  });
+});
+
+describe('initModernDropdown', () => {
+  it('should not call Tippy if there is no element with [data-button-with-dropdown]', () => {
+    expect(tippy.default).not.toHaveBeenCalled();
+
+    initModernDropdown();
+
+    expect(tippy.default).not.toHaveBeenCalled();
+  });
+
+  it('should call the Tippy util with the [data-button-with-dropdown-toggle] attribute', () => {
+    const html = `
+    <div data-button-with-dropdown>
+      <button id="button" data-button-with-dropdown-toggle>...</button>
+      <div id="content" data-button-with-dropdown-content>
+        Content
+      </div>
+    </div>`;
+    document.body.innerHTML = html;
+
+    const content = document.getElementById('content');
+
+    expect(tippy.default).not.toHaveBeenCalled();
+
+    initModernDropdown();
+
+    expect(tippy.default).toHaveBeenLastCalledWith(
+      document.getElementById('button'),
+      expect.objectContaining({
+        content,
+        trigger: 'click',
+        interactive: true,
+        theme: 'dropdown',
+        placement: 'bottom',
+      }),
+    );
+  });
+});

client/src/includes/initTooltips.ts

@@ -1,11 +1,14 @@
-import tippy from 'tippy.js';
+import tippy, { Content, Props, Instance } from 'tippy.js';
 
+/**
+ * Hides tooltip when escape key is pressed
+ */
 const hideTooltipOnEsc = {
   name: 'hideOnEsc',
   defaultValue: true,
-  fn({ hide }) {
-    function onKeyDown(e) {
-      if (e.key === 'Escape') {
+  fn({ hide }: Instance) {
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.key === 'Escape') {
         hide();
       }
     }
@@ -21,12 +24,12 @@ const hideTooltipOnEsc = {
   },
 };
 
-/*
- Prevents the tooltip from staying open when the breadcrumbs expand and push the toggle button in the layout
+/**
+ * Prevents the tooltip from staying open when the breadcrumbs expand and push the toggle button in the layout
  */
 const hideTooltipOnBreadcrumbExpandAndCollapse = {
   name: 'hideTooltipOnBreadcrumbAndCollapse',
-  fn({ hide }) {
+  fn({ hide }: Instance) {
     function onBreadcrumbExpandAndCollapse() {
       hide();
     }
@@ -56,12 +59,12 @@ const hideTooltipOnBreadcrumbExpandAndCollapse = {
   },
 };
 
-/*
- If the toggle button has a toggle arrow, rotate it when open and closed
+/**
+ * If the toggle button has a toggle arrow, rotate it when open and closed
  */
 const rotateToggleIcon = {
   name: 'rotateToggleIcon',
-  fn(instance) {
+  fn(instance: Instance) {
     const dropdownIcon = instance.reference.querySelector('.icon-arrow-down');
 
     if (!dropdownIcon) {
@@ -76,7 +79,7 @@ const rotateToggleIcon = {
 };
 
 /**
- Default Tippy Tooltips
+ * Default Tippy Tooltips
  */
 export function initTooltips() {
   tippy('[data-tippy-content]', {
@@ -85,13 +88,13 @@ export function initTooltips() {
 }
 
 /**
- Actions Dropdown
- <div data-button-with-dropdown>
- <button data-button-with-dropdown-toggle>
- <div data-button-with-dropdown-content>
- </div>
+ * Actions Dropdown initialisation using the Tippy library.
+ * @example
+ * <div data-button-with-dropdown>
+ *  <button data-button-with-dropdown-toggle>...</button>
+ *  <div data-button-with-dropdown-content></div>
+ * </div>
  */
-
 export function initModernDropdown() {
   const containers = document.querySelectorAll('[data-button-with-dropdown]');
 
@@ -99,13 +102,13 @@ export function initModernDropdown() {
     const content = container.querySelector(
       '[data-button-with-dropdown-content]',
     );
-    const toggle = container.querySelector(
+    const toggle: HTMLElement | null = container.querySelector(
       '[data-button-with-dropdown-toggle]',
     );
 
     // Adding data-hover-tooltip-content="Tooltip Text" to the toggle element will give you a tooltip on hover as well
-    const hoverTooltip = toggle.dataset.hoverTooltipContent;
-    let hoverTooltipInstance;
+    const hoverTooltip = toggle?.dataset.hoverTooltipContent;
+    let hoverTooltipInstance: Instance;
 
     if (toggle) {
       if (content) {
@@ -120,8 +123,11 @@ export function initModernDropdown() {
         });
       }
 
-      tippy(toggle, {
-        content: content,
+      /**
+       * Default Tippy Options
+       */
+      const tippyOptions: Partial<Props> = {
+        content: content as Content,
         trigger: 'click',
         interactive: true,
         theme: 'dropdown',
@@ -141,7 +147,9 @@ export function initModernDropdown() {
             hoverTooltipInstance.enable();
           }
         },
-      });
+      };
+
+      tippy(toggle, tippyOptions);
     }
   });
 }

docs/releases/4.2.md

@@ -34,6 +34,7 @@ depth: 1
  * Clean up linting on legacy code and add shared util `hasOwn` in TypeScript (Loveth Omokaro)
  * Remove unnecessary box-sizing: border-box declarations in SCSS (Albina Starykova)
  * Add full support for secondary buttons with icons in the Wagtail design system - `button bicolor button--icon button-secondary` including the `button-small` variant (Seremba Patrick)
+ * Migrated `initTooltips` to TypeScript add JSDoc and unit tests (Fatuma Abdullahi)
 
 ### Bug fixes