@utahdts/utah-design-system-header 1.2.0 → 1.3.0

package/src/js/misc/findRecursive.js

@@ -0,0 +1,39 @@
+// @ts-check
+
+/**
+ * recursively searches through an object for fields that match a custom function like when a menu is
+ * searching if it or any of its children are selected.
+ *
+ * @template T
+ * @param {T[] | T} object the object on which to start searching
+ * @param {string[]} recursiveFields which fields on the object should be "dug" in to recursively
+ * @param {(o: T) => boolean} isMatchFunc the function to call on each child to see if it matches
+ * @returns {boolean} true if the isMatchFunc is true for the root or any of its children
+ */
+export default function findRecursive(object, recursiveFields, isMatchFunc) {
+  /** @type {boolean} */
+  let result = false;
+
+  if (object) {
+    if (Array.isArray(object)) {
+      // try each item in the array separately
+      result = object.some((o) => findRecursive(o, recursiveFields, isMatchFunc));
+    } else {
+      // does this object match?
+      result = isMatchFunc(object);
+
+      if (!result) {
+        // object didn't match so try its children
+        result = (
+          !!recursiveFields
+            // @ts-ignore
+            ?.filter((field) => object[field])
+            // @ts-ignore
+            ?.some((field) => findRecursive(object[field], recursiveFields, isMatchFunc))
+        );
+      }
+    }
+  }
+
+  return result;
+}

package/src/js/misc/isString.js

@@ -0,0 +1,8 @@
+// @ts-check
+/**
+ * @param {any} s candidate for being a string
+ * @returns {boolean} true if javascript thinks `s` is a string
+ */
+export default function isString(s) {
+  return typeof s === 'string' || s instanceof String;
+}

package/src/js/misc/isTouchDevice.js

@@ -0,0 +1,9 @@
+// https://www.geeksforgeeks.org/how-to-detect-touch-screen-device-using-javascript/
+export default function isTouchDevice() {
+  return (
+    ('ontouchstart' in window)
+    || (navigator.maxTouchPoints > 0)
+    // @ts-ignore
+    || (navigator.msMaxTouchPoints > 0)
+  );
+}

package/src/js/misc/jsDocTypes.js

@@ -0,0 +1,235 @@
+// @ts-check
+
+// Types of Events: https://www.w3schools.com/jsref/obj_events.asp
+
+/**
+ *
+ * JsDoc types for the utah header. Types help lower the mental load of object properties as well as
+ * helps find "bugs" from invalid typings scenarios.
+ *
+ * @typedef {Element} ChildNode
+ *
+ * @typedef {(function(MouseEvent | TouchEvent | KeyboardEvent): void)} EventAction
+ *
+ * @interface Partial - typescript has "Partial" built-in while JSDoc does not know about "type utilities"
+ *
+ * @typedef {'SMALL' | 'MEDIUM' | 'LARGE'} Size
+ * Should be Synced with the enumerations/sizes object
+ *
+ * @typedef {'dialog' | 'grid' | 'listbox' | 'menu' | 'tree'} AriaHasPopupType
+ *
+ * @typedef MainMenuItem {
+ *  // this started as a copy of MenuItem but can diverge to be its own thing
+ *  // wordpress has the concept of a menu item that is a link AND has children, but when it goes mobile the link is no longer available
+ *  // so the wordpress conversion script will take a menu that has a link and children and auto insert the link as the first child
+ *  // so this could do that work automatically if it detects that scenario instead of throwing an error
+ *
+ *  // should be only one of the following three action types
+ *  //   actionUrl: an <a> with a url for navigation
+ *  //   actionFunction: a <button> that when triggered calls a function
+ *  //   actionFunctionUrl: an <a> that when triggered calls a function (for Single Page Apps)
+ *  //   actionMenu: a <button> that when triggered exposes a sub menu of options
+ *  @property {MenuItemUrlAction} [actionUrl] - link url
+ *  @property {EventAction} [actionFunction] - onClick function
+ *  @property {MenuItemFunctionUrlAction} [actionFunctionUrl] - single page apps render an <a> but call browser push; you should handle cmd click
+ *  @property {MenuItem[]} [actionMenu] - children menus
+*
+ *  @property {ChildrenMenuType} [childrenMenuType] - default is "flyout"
+ *  @property {string} [className] - can be used for `selected` or any other purpose
+ *  @property {ChildNode} [icon] - icon to show next to this menu item
+ *  @property {boolean} [isDivider] - this menu item is a divider between other menu items
+ *  @property {boolean} [isSelected] - is this menu item currently a selected thing (on its page?)
+ *  @property {string} title - title for the menu item
+ * }
+ *
+ * @typedef {'none' | 'a1' | 'a2' | 'a3' | 'custom' | 'unittest'} Environments
+ *
+ * @typedef {'utahHeaderLoaded' | 'utahHeaderUnloaded'} Events
+ *
+ * @typedef MainMenu {
+ *  @property {MainMenuItem[]} menuItems
+ *  @property {string} title
+ * }
+ *
+ * For menu items that are links to other locations
+ * @typedef MenuItemUrlAction {
+ *  @property {string} url - the url to which to go when interacted with
+ *  @property {boolean} [openInNewTab] - true to have the link open in a new window defaults to `false` if not provided
+ * }
+ *
+ * @typedef MenuItemFunctionUrlAction {
+ *  // actually going to call this function to do what you want
+ *  @property {EventAction} actionFunction - onClick custom function to call when triggered
+ *  @property {boolean} [skipHandleEvent] - should handleEvent automatically be used to call your function to stop propagation and prevent default
+ *
+ *  // trick the user to think it's a normal link; you must set these to the correct values to match your custom function
+ *  @property {boolean} [openInNewTab] - true to have the link say it will open in a new window; defaults to `false`
+ *  @property {string} url - the url to show when hovered
+ * }
+ *
+ * A menu item in the menu, can have children
+ * @typedef MenuItem {
+ *  // should be only one of the following three action types
+ *  //   actionUrl: an <a> with a url for navigation
+ *  //   actionFunction: a <button> that when triggered calls a function
+ *  //   actionFunctionUrl: an <a> that when triggered calls a function (for Single Page Apps)
+ *  //   actionMenu: a <button> that when triggered exposes a sub menu of options
+ *  @property {MenuItemUrlAction} [actionUrl] - link url
+ *  @property {EventAction} [actionFunction] - onClick function
+ *  @property {MenuItemFunctionUrlAction} [actionFunctionUrl] - single page apps render an <a> but call browser push; you should handle cmd click
+ *  @property {MenuItem[]} [actionMenu] - children menus
+ *
+ *  @property {string} [className] - can be used for `selected` or any other purpose
+ *  @property {ChildNode} [icon] - icon to show next to this menu item
+ *  @property {boolean} [isDivider] - this menu item is a divider between other menu items
+ *  @property {boolean} [isSelected] - is this menu item currently a selected thing (on its page?)
+ *  @property {string} title - title for the menu item
+ * }
+ *
+ * @typedef PopupMenu {
+ *  @property {string} [className] - className to put on the popupMenu
+ *  @property {MenuItem[]} menuItems - the menu items to show in the menu
+ *  @property {string} title - the title of the menu
+ * }
+ *
+ * @typedef MediaSizes {
+ *   @property {number} mobile - mobile sized render area
+ *   @property {number} tabletLandscape - table landscape sized render area
+ *   @property {number} tabletPortrait - table portrait sized render area
+ * }
+ *
+ * these match the popper's position options
+ * @typedef {'auto' | 'auto-start' | 'auto-end' |
+ *   'bottom' | 'bottom-start' | 'bottom-end' |
+ *    'left' | 'left-start' | 'left-end' |
+ *    'right' | 'right-start' | 'right-end' |
+ *    'top' | 'top-start' | 'top-end'
+ * } PopupPlacement
+ *
+ * @typedef PopupFocusHandlerOptions {
+ *  @property {() => boolean} [isPerformPopup] should the popup pop open? Helpful for utahId that doesn't pop until user loaded
+ *  @property {function(UIEvent): void} [onClick] custom onclick handler
+ *  @property {PopupPlacement} [popupPlacement] which side should the popup place itself (defaults to bottom and popper will place where it can)
+ *  @property {boolean} [preventOnClickHandling] turns off click handling for popup invocation
+ *  @property {boolean} [shouldFocusOnHover] will perform the popup on hover as well as the focus event
+ * }
+ *
+ * @typedef RenderPopupOptions {
+ *  @property {boolean} [removePopupArrow] allows removing the popup border arrow for flyouts
+ * }
+ *
+ * @typedef {('flyout' | 'inline' | 'mega-menu')} ChildrenMenuType
+ * @typedef RenderPopupMenuOptions {
+ *   @property {ChildrenMenuType} childrenMenuType
+ *   - flyout: children in new popup
+ *   - inline: expandable children
+ *   - mega-menu: always expanded children
+ *   @property {boolean} [removePopupArrow] allows removing the popup border arrow for flyouts
+ * }
+ *
+ * @typedef Badge {
+ *  @property {string} [className] - a class to add to the badge for custom formatting like color
+ *  @property {string} label - the label for the screen reader to read describing the badge
+ *  @property {number} [value] - the value to show in the badge
+ * }
+ *
+ * @typedef ActionItem {
+ *  // should be only one of the following three action types
+ *  @property {EventAction} [actionFunction] - func: onClick callback
+ *  @property {PopupMenu} [actionPopupMenu] - Object[]: array of MenuItems
+ *  @property {function (): HTMLElement | string} [actionDom] - ChildNode: content in a popup.
+ *
+ *  @property {string} [className] - CSS classes for the action item
+ *  @property {Badge} [badge] - the badge to show in the action item's badge icon
+ *  @property {HTMLElement | string} icon - DOM or DOM string of icon to show
+ *  @property {'left' | 'none' | 'right'} [mobileMenuLocation] - positioned right or left of the Utah ID button? not at all? default is none
+ *  @property {boolean} showTitle - Should the title always be visible?
+ *  @property {string} title - Title of the action item (required for accessibility)
+ * }
+ *
+ * // must use one and only one of the properties here
+ * @typedef DomLocationTarget {
+ *  @property {string} [cssSelector] - find a target DOM element by document.querySelector(cssSelector) (throws error if not found)
+ *  @property {HTMLElement} [element] - insert the header as a child of this given element
+ *  @property {function (): HTMLElement} [elementFunction] - insert the header in to whatever element is returned from this function
+ * }
+ *
+ * @typedef GlobalEventType {
+ *  @property {(e: MouseEvent) => void} globalOnClick the current event handler for global on click events
+ *  @property {(e: KeyboardEvent) => void} globalOnKeydown tracks when keys are pressed down
+ *  @property {(e: KeyboardEvent) => void} globalOnKeyup the current event handler for global on key press events
+ * }
+ *
+ * Partial is a `typescript` utility that takes a type and makes all its properties optional. This works in vs-code IDEs but may
+ * be problematic in other IDEs that don't support typescript "out of the box".
+ // eslint-disable-next-line jsdoc/no-undefined-types
+ * @typedef {Partial<Settings>} SettingsInput
+ *
+ * // User fields from the UtahId authority
+ * @typedef UserInfo {
+ *  @property {boolean} authenticated - the current information is ratified with the authority
+ *  @property {boolean | null | undefined} [disabled]
+ *  @property {string | undefined} [env] - the UtahId environment
+ *  @property {string | null | undefined} first - the name shown on the UtahId button when logged in
+ *  @property {string | null | undefined} [id]
+ *  @property {string | null | undefined} [last]
+ *  @property {string[] | null | undefined} [mail]
+ *  @property {string | null | undefined} [middle]
+ *  @property {string | null | undefined} [status]
+ *  @property {string | undefined} [type]
+ *  @property {string | null | undefined} [username]
+ * }
+ *
+ * @typedef {'Automatic' | 'None' | 'Provided'} UtahIdFetchStyle
+ *
+ * @typedef UtahIdData {
+ *  @property {boolean | null} isDefinitive - true when the user's state is known, false while the ajax request is inflight
+ *  @property {string | null} lastError - true when the user's state is known, false while the ajax request is inflight
+ *  @property {UserInfo | null} userInfo - the current logged in user info or null if not found
+ * }
+ *
+ * // only fill in what you want to change, the rest will be defaults
+ * // The UtahID header will auto fetch the user from UtahID if it is not told that your application will be controlling the signed in user
+ * // This may cause the header to jump as data comes from UtahID and your application gets data from its data source.
+ * // To prevent this jankiness, your application should call setUtahHeaderSettings with a userInfo.currentUser value of `null`. This way
+ * // the header knows not to fetch the user and your application can later call setSettings again with the current user.
+ * @typedef UtahIDSettings {
+ *  @property {UserInfo | undefined | null} currentUser - null: app controls the user, undefined: header will fetch current user
+ *  @property {function(UtahIdData): void | undefined} [onAuthChanged] - auth user changes, eg (newUserData) => { ... do something ... }
+ *  @property {function(UIEvent): void | undefined} [onProfile] - when the UtahId's menu item for the user's profile is triggered: (e) => { }
+ *  @property {function(UIEvent): void | undefined} [onSignIn] - when the UtahId button is pressed to sign in: (e) => { }
+ *  @property {function(UIEvent): void | undefined} [onSignOut] - when the UtahId's menu item for sign out is triggered: (e) => { }
+ *  @property {MenuItem[] | undefined} [menuItems] - menu items to add to the UtahId menu (user must be logged in to open the menu): (e) => { }
+ * }
+ *
+ * @typedef Logo {
+ *  @property {HTMLElement | function(): HTMLElement} [element] an HTML Element to render
+ *  @property {string | function(): string} [htmlString] string containing html that will be rendered
+ *  @property {string | function(): string} [imageUrl] url to an image
+ * }
+ *
+ * @typedef FooterSettings {
+ *  @property {DomLocationTarget} [domLocationTarget] - where in the DOM should the footer be inserted? (defaults to the bottom of the body)
+ *  @property {boolean} [showHorizontalRule] - true to have a dividing horizontal rule placed at the top of the footer for dividing footer content
+ * }
+ *
+ * // !! Make sure to update SettingsShape in the library if this changes !!
+ * @typedef Settings {
+ *  @property {ActionItem[]} [actionItems] - action items to show in the header
+ *  @property {DomLocationTarget} [domLocationTarget] - where in the DOM should the header be inserted? (defaults to the top of the body)
+ *  @property {FooterSettings | null} [footer] - null means to not show the footer
+ *  @property {Logo} [logo] - the logo to show
+ *  @property {MainMenu | false} [mainMenu] - the main menu to show on a line below the citizen experience/unbrand line
+ *  @property {MediaSizes} mediaSizes - sizes for triggering media queries
+ *  @property {((search: string) => void) | false} [onSearch] - if onSearch is provided, the search icon will show in the main menu bar
+ *  @property {boolean} showTitle - should the title be shown (it will always be on the page for accessibility)
+ *  @property {string} size - size has to be one of the `Size` types
+ *  @property {string} title - the title to place at the top of the page (can be hidden) but needs to be there for accessibility
+ *  @property {string} titleURL - when the agency title is triggered, the browser navigates to this url
+ *  @property {UtahIDSettings | boolean} [utahId] - settings for the utahId button; true = turned on, false = turned off, object = custom
+ * }
+ *
+ */
+
+// without this export, `@typedef import` reports this file 'is not a module'... (눈_눈)
+export default false;

package/src/js/misc/notNull.js

@@ -0,0 +1,15 @@
+/**
+ * https://docs.joshuatz.com/cheatsheets/js/jsdoc/#non-null-assertion-in-jsdoc
+ * Exclude in JSDoc removes a type from another type. The returned `T` no longer has `null` nor `undefined` in its type
+ *
+ * @template T
+ * @param {T} value
+ * @param {string} errorMessage
+ * @returns {NonNullable<T>}
+ */
+export default function notNull(value, errorMessage) {
+  if (value === null || value === undefined) {
+    throw new Error(errorMessage);
+  }
+  return value;
+}

package/src/js/misc/popupFocusHandler.js

@@ -0,0 +1,209 @@
+// @ts-check
+import { createPopper } from '@popperjs/core';
+import domConstants, { getCssClassSelector } from '../enumerations/domConstants';
+import popupPlacement from '../enumerations/popupPlacement';
+import { hideAllMenus } from '../lifecycle/globalEvents';
+import isTouchDevice from './isTouchDevice';
+import showHideElement from './showHideElement';
+import checkForError from './checkForError';
+
+/*
+   ___     ___    _  _   _   _____     _____    ___    _   _    ___   _  _
+  |   \   / _ \  | \| | ( ) |_   _|   |_   _|  / _ \  | | | |  / __| | || |
+  | |) | | (_) | | .` | |/    | |       | |   | (_) | | |_| | | (__  | __ |
+  |___/   \___/  |_|\_|       |_|       |_|    \___/   \___/   \___| |_||_|
+
+  If you do dare touch this, and you probably should if you need to, here are the testing scenarios to consider:
+  * have an action item (divisions) that pops open a menu with children
+    * tab through the action item so that the popup opens and tab through children so that they toggle open
+    * tabbing out of focus of the action item and children menus should then close the popup
+  * have two action items with popups (menu popup and dom content popup)
+    * click on one of the action icons to open the popup
+    * click on the other action icon to open its popup and close the other popup
+    * there was a point in time where the original popup was not closing
+  * have a header menu item with at least 3 levels deep of menu items
+    * tab to the children at the deepest level and make sure that the sub menus flyout
+  * accessibility: have an action item (divisions) that has a popup menu with children
+    * without tabbing or clicking, use accessibility (ctrl+opt+right-arrow) to move on top of the divisions action item
+    * trigger the menu (ctrl+opt+space) to have the menu toggle open
+  * do the same test as above but with the Utah ID button after logging in so that it opens the Utah Id menu
+  * have a main menu item whose children flyout and make sure hovering causes those menu items to flyout
+  * tab to a child menu in a popup menu that also has children menus
+    * this "middle" menu (has parent and children) when first focused should not have its chevron open nor show its children
+    * tabbing again to see this menu's children then opens the children and toggles the chevron
+
+  Notes:
+  * mobile devices do not have focus events. This caused issues with putting logic in focus that would work in browser but not
+    in mobile and vice/versa.
+  * when targeting items via accessibility navigation (not tab key), items do not receive focus, so focus events again were
+    problematic.
+  * Added a timeout to the open/close because the focusin, mousedown, and onclick were fighting with timing issues
+    * sometimes onfocusin would fire first, other times onmousedown would fire first
+    * and they would cause each other to see different statuses because one would open and another would close the menu
+*/
+
+/**
+ * @typedef {import('../misc/jsDocTypes').AriaHasPopupType} AriaHasPopupType
+ * @typedef {import('../misc/jsDocTypes').PopupFocusHandlerOptions} PopupFocusHandlerOptions
+ */
+
+/**
+ * Tracking focus of a wrapper that has a button for toggling and a popup inside of it
+ * for both onClicks AND tabbing to focus is pretty complicated. The idea is that while the
+ * button OR menu has focus, the menu is shown. Also global events like clicking off the wrapper
+ * or pressing escape should also close the popup.
+ *
+ * @param {HTMLElement} wrapper the wrapper containing the button and popup
+ * @param {HTMLElement} button the button that toggles the popup to open/close
+ * @param {HTMLElement} popup the actual popup being opened and closed
+ * @param {AriaHasPopupType} ariaHasPopup aria tag for popup type
+ * @param {PopupFocusHandlerOptions | undefined} options
+ */
+export default function popupFocusHandler(wrapper, button, popup, ariaHasPopup, options) {
+  let delayPopupTimeoutId = NaN;
+  let delayHideTimeoutId = NaN;
+  const TIMEOUT_MS_LONG = 300;
+  const TIMEOUT_MS_MEDIUM = 150;
+  const TIMEOUT_MS_SHORT = 50;
+
+  button.setAttribute('aria-expanded', 'false');
+  button.setAttribute('aria-haspopup', ariaHasPopup);
+
+  /*
+     ___     ___    _  _   _   _____     _____    ___    _   _    ___   _  _
+    |   \   / _ \  | \| | ( ) |_   _|   |_   _|  / _ \  | | | |  / __| | || |
+    | |) | | (_) | | .` | |/    | |       | |   | (_) | | |_| | | (__  | __ |
+    |___/   \___/  |_|\_|       |_|       |_|    \___/   \___/   \___| |_||_|
+  */
+  /**
+   * @param {number} delayMS
+   */
+  function performPopup(delayMS) {
+    clearTimeout(delayPopupTimeoutId);
+    clearTimeout(delayHideTimeoutId);
+
+    if (!options?.isPerformPopup || (options?.isPerformPopup && options.isPerformPopup())) {
+      delayPopupTimeoutId = window.setTimeout(
+        () => {
+          createPopper(button, popup, {
+            placement: options?.popupPlacement || popupPlacement.BOTTOM,
+            modifiers: [
+              {
+                name: 'offset',
+                options: { offset: [0, 11] },
+              },
+            ],
+          });
+          showHideElement(popup, true, domConstants.POPUP__VISIBLE, domConstants.POPUP__HIDDEN);
+          button.setAttribute('aria-expanded', 'true');
+
+          // hide all tooltips
+          document.querySelectorAll(getCssClassSelector(domConstants.TOOLTIP__WRAPPER))
+            .forEach((tooltip) => tooltip.classList.add(domConstants.TOOLTIP__WRAPPER__HIDDEN));
+        },
+        delayMS
+      );
+    }
+  }
+
+  /*
+     ___     ___    _  _   _   _____     _____    ___    _   _    ___   _  _
+    |   \   / _ \  | \| | ( ) |_   _|   |_   _|  / _ \  | | | |  / __| | || |
+    | |) | | (_) | | .` | |/    | |       | |   | (_) | | |_| | | (__  | __ |
+    |___/   \___/  |_|\_|       |_|       |_|    \___/   \___/   \___| |_||_|
+  */
+  /**
+   * @param {number} delayMS
+   */
+  function hidePopup(delayMS) {
+    clearTimeout(delayPopupTimeoutId);
+    clearTimeout(delayHideTimeoutId);
+    if (!options?.isPerformPopup || options.isPerformPopup()) {
+      delayHideTimeoutId = window.setTimeout(
+        () => {
+          showHideElement(popup, false, domConstants.POPUP__VISIBLE, domConstants.POPUP__HIDDEN);
+          button.setAttribute('aria-expanded', 'false');
+        },
+        delayMS
+      );
+    }
+  }
+
+  /*
+     ___     ___    _  _   _   _____     _____    ___    _   _    ___   _  _
+    |   \   / _ \  | \| | ( ) |_   _|   |_   _|  / _ \  | | | |  / __| | || |
+    | |) | | (_) | | .` | |/    | |       | |   | (_) | | |_| | | (__  | __ |
+    |___/   \___/  |_|\_|       |_|       |_|    \___/   \___/   \___| |_||_|
+  */
+  if (options?.preventOnClickHandling) {
+    // eslint-disable-next-line no-param-reassign
+    checkForError(!!wrapper.onclick, 'popupFocusHandler: wrapper already has an onclick');
+    // eslint-disable-next-line no-param-reassign
+    wrapper.onclick = (e) => {
+      // for menus that are both a link and have children menus, when doing a popup, prevent clicking
+      // from doing anything so that the popup menu doesn't go away on the click. The link for the
+      // menu will be a separate menu item.
+      e.preventDefault();
+      e.stopPropagation();
+    };
+  } else {
+    wrapper.addEventListener('focusin', () => performPopup(TIMEOUT_MS_MEDIUM));
+
+    wrapper.addEventListener('focusout', () => hidePopup(TIMEOUT_MS_MEDIUM));
+  }
+
+  if (options?.shouldFocusOnHover) {
+    wrapper.addEventListener('mouseenter', () => performPopup(TIMEOUT_MS_LONG));
+    wrapper.addEventListener('mouseleave', () => hidePopup(TIMEOUT_MS_LONG));
+  }
+
+  /*
+     ___     ___    _  _   _   _____     _____    ___    _   _    ___   _  _
+    |   \   / _ \  | \| | ( ) |_   _|   |_   _|  / _ \  | | | |  / __| | || |
+    | |) | | (_) | | .` | |/    | |       | |   | (_) | | |_| | | (__  | __ |
+    |___/   \___/  |_|\_|       |_|       |_|    \___/   \___/   \___| |_||_|
+  */
+
+  if (!options?.preventOnClickHandling) {
+    if (button.onclick) {
+      throw new Error('popupFocusHandler: button already has onclick');
+    }
+    // eslint-disable-next-line no-param-reassign
+    button.onclick = (e) => {
+      const wasAlreadyOpen = button.getAttribute('aria-expanded') === 'true';
+      // for click popups
+      if (!options?.isPerformPopup || options.isPerformPopup()) {
+        e.stopPropagation();
+        e.preventDefault();
+        /*
+           ___     ___    _  _   _   _____     _____    ___    _   _    ___   _  _
+          |   \   / _ \  | \| | ( ) |_   _|   |_   _|  / _ \  | | | |  / __| | || |
+          | |) | | (_) | | .` | |/    | |       | |   | (_) | | |_| | | (__  | __ |
+          |___/   \___/  |_|\_|       |_|       |_|    \___/   \___/   \___| |_||_|
+        */
+
+        // if !wasAlreadyOpen but aria-expanded is "true" then the 'focusin' opened it (tabbed to it?)
+        if (wasAlreadyOpen && button.getAttribute('aria-expanded') === 'true') {
+          hidePopup(TIMEOUT_MS_SHORT);
+          /** @type {HTMLElement | null} */(document.activeElement)?.blur();
+        } else {
+          if (isTouchDevice()) {
+            hideAllMenus();
+          }
+          performPopup(TIMEOUT_MS_SHORT);
+        }
+      }
+      if (options?.onClick) {
+        options.onClick(e);
+      }
+    };
+  }
+}
+/*
+   ___     ___    _  _   _   _____     _____    ___    _   _    ___   _  _
+  |   \   / _ \  | \| | ( ) |_   _|   |_   _|  / _ \  | | | |  / __| | || |
+  | |) | | (_) | | .` | |/    | |       | |   | (_) | | |_| | | (__  | __ |
+  |___/   \___/  |_|\_|       |_|       |_|    \___/   \___/   \___| |_||_|
+
+  -- see top for details --
+*/

package/src/js/misc/renderDOMSingle.js

@@ -0,0 +1,61 @@
+// @ts-check
+
+import isString from './isString';
+
+/**
+ * Render a DOM from a string and return just the DOM child node
+ * or HTMLCollection if there is more than one Node rendered
+ * @param {string} str - HTML string to become rendered DOM
+ * @returns {HTMLCollection | Element}
+ */
+function renderDOM(str) {
+  const domParser = new DOMParser();
+
+  /** @type {HTMLCollection | Element} */
+  let result;
+  if (isString(str)) {
+    const rendered = /** @type {Document} */ (isString(str) ? domParser.parseFromString(str, 'text/html') : str);
+
+    const maybeResult = (
+      rendered.body.children.length > 1
+        ? rendered.body.children
+        : rendered.body.children.item(0)
+    );
+    if (!maybeResult) {
+      // eslint-disable-next-line no-console
+      console.error(str);
+      throw new Error('renderDOM: nothing rendered');
+    }
+    result = maybeResult;
+  } else if (/** @type {unknown} */ (str) instanceof Element) {
+    result = str;
+  } else if (!str) {
+    throw new Error('renderDOM: falsy string passed; cannot render nothing');
+  } else {
+    // eslint-disable-next-line no-console
+    console.error(str);
+    throw new Error(`renderDOM: str is not a string nor a DOM Element : '${str}'`);
+  }
+  return result;
+}
+
+/**
+ * Pull first element out of a collection if a collection was rendered
+ *
+ * @param {string | HTMLElement} str
+ * @returns {HTMLElement}
+ */
+export default function renderDOMSingle(str) {
+  const dom = typeof str === 'string' ? renderDOM(str) : str;
+  if (dom instanceof HTMLCollection && dom.length > 1) {
+    throw new Error('renderDOMSingle: must render a single element');
+  }
+  /** @type HTMLElement | null */
+  const firstChild = /** @type HTMLElement | null */ (dom instanceof HTMLCollection ? dom[0] : dom);
+  if (!firstChild) {
+    // eslint-disable-next-line no-console
+    console.error(str);
+    throw new Error('renderDOMSingle: nothing rendered');
+  }
+  return firstChild;
+}

package/src/js/misc/showHideElement.js

@@ -0,0 +1,15 @@
+/**
+ * @param {Element} element
+ * @param {boolean} isShown
+ * @param {string} visibleClass
+ * @param {string} hiddenClass
+ */
+export default function showHideElement(element, isShown, visibleClass, hiddenClass) {
+  if (isShown) {
+    element.classList.remove(hiddenClass);
+    element.classList.add(visibleClass);
+  } else {
+    element.classList.add(hiddenClass);
+    element.classList.remove(visibleClass);
+  }
+}

package/src/js/misc/toHash.js

@@ -0,0 +1,18 @@
+/* eslint-disable no-bitwise */
+
+/** https://stackoverflow.com/a/8076436/1478933
+ * @param {object | string} thing the thing to hash
+ */
+export default function toHash(thing) {
+  let hash = 0;
+  const string = JSON.stringify(thing);
+  for (let i = 0; i < string.length; i += 1) {
+    const code = string.charCodeAt(i);
+    hash = ((hash << 5) - hash) + code;
+
+    // Convert to 32bit integer
+    hash &= hash;
+  }
+
+  return hash;
+}

package/src/js/misc/uuidv4.js

@@ -0,0 +1,8 @@
+// @ts-nocheck
+export default function uuidv4() {
+  return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace(
+    /[018]/g,
+    // eslint-disable-next-line no-bitwise
+    (c) => (c ^ crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> c) / 4).toString(16)
+  );
+}

package/src/js/misc/valueOrFunctionValue.js

@@ -0,0 +1,13 @@
+/**
+ * @template ValueOrFunctionValueT
+ * @param {ValueOrFunctionValueT | function(): ValueOrFunctionValueT} valueOrFunction
+ * @returns {ValueOrFunctionValueT}
+ */
+export default function valueOrFunctionValue(valueOrFunction) {
+  return (
+    (typeof valueOrFunction === 'function')
+      // @ts-ignore
+      ? valueOrFunction()
+      : valueOrFunction
+  );
+}

package/src/js/renderables/_html/NewTabAccessibility.html

@@ -0,0 +1,4 @@
+<span class="utds-new-tab-link-a11y">
+  <span class="visually-hidden">, opens in a new tab</span>
+  <span class="utds-icon-after-external-link" aria-hidden="true"></span>
+</span>