@utahdts/utah-design-system 1.15.5 → 1.16.1

package/react/components/navigation/VerticalMenu.jsx

@@ -1,34 +1,71 @@
+import { childrenMenuTypes } from '@utahdts/utah-design-system-header';
 import { joinClassNames } from '../../util/joinClassNames';
-import { MenuItem } from './MenuItem';
+import { MenuItemInline } from './items/MenuItemInline';
+import { MenuItemPlain } from './items/MenuItemPlain';
+import { MenuItemFlyout } from './items/MenuItemFlyout';
+import { menuTypes } from '../../enums/menuTypes';
 
 /** @typedef {import('@utahdts/utah-design-system').WebsiteMainMenu} WebsiteMainMenu */
 /** @typedef {import('@utahdts/utah-design-system').WebsiteMainMenuItem} WebsiteMainMenuItem */
 
 /**
  * @param {object} props
+ * @param {string} [props.className]
  * @param {WebsiteMainMenu | WebsiteMainMenuItem} [props.currentMenuItem]
  * @param {WebsiteMainMenu[]} props.menus
  * @returns {import('react').JSX.Element}
  */
-export function VerticalMenu({ currentMenuItem, menus }) {
+export function VerticalMenu({ className, currentMenuItem, menus }) {
   return (
     <>
       {
         menus.map((menu) => {
           const TitleTagName = menu.titleTagName || 'h2';
           return (
-            <nav className="menu-side-panel" key={`side-panel-navigation-menu__${menu.id}`} aria-labelledby={menu.id}>
+            <nav className={className} key={`vertical-menu__${menu.id}`} aria-labelledby={menu.id}>
               {/* @ts-ignore */}
               <TitleTagName
                 id={menu.id}
-                className={joinClassNames(menu.titleTagClassName, 'menu-side-panel__header')}
+                className={joinClassNames(menu.titleTagClassName, 'vertical-menu__header')}
               >
                 {menu.header}
               </TitleTagName>
-              <ul key={`side-panel-navigation-menu__${menu.id}`} role="menu">
-                {menu.menuItems.map((menuItem) => (
-                  <MenuItem currentMenuItem={currentMenuItem} menuItem={menuItem} key={`menu-side-panel__menu-item__${menuItem.link}-${menuItem.title}}`} />
-                ))}
+              <ul key={`vertical-menu__list__${menu.id}`} role="menu" className="vertical-menu">
+                {menu.menuItems.map((menuItem) => {
+                  let result;
+                  switch (menuItem.childrenMenuType) {
+                    case childrenMenuTypes.INLINE:
+                      result = (
+                        <MenuItemInline
+                          menuType={menuTypes.VERTICAL}
+                          currentMenuItem={currentMenuItem}
+                          menuItem={menuItem}
+                          key={`vertical-menu__menu-item__${menuItem.link}-${menuItem.title}}`}
+                        />
+                      );
+                      break;
+                    case childrenMenuTypes.FLYOUT:
+                      result = (
+                        <MenuItemFlyout
+                          menuType={menuTypes.VERTICAL}
+                          currentMenuItem={currentMenuItem}
+                          menuItem={menuItem}
+                          key={`vertical-menu__menu-item__${menuItem.link}-${menuItem.title}}`}
+                        />
+                      );
+                      break;
+                    default:
+                      result = (
+                        <MenuItemPlain
+                          menuType={menuTypes.VERTICAL}
+                          menuItem={menuItem}
+                          key={`vertical-menu__menu-item__${menuItem.link}-${menuItem.title}}`}
+                          currentMenuItem={currentMenuItem}
+                        />
+                      );
+                  }
+                  return result;
+                })}
               </ul>
             </nav>
           );

package/react/components/navigation/items/MenuItemFlyout.jsx

@@ -0,0 +1,119 @@
+import { NavLink } from 'react-router-dom';
+import { useImmer } from 'use-immer';
+import { useRef } from 'react';
+import { usePopper } from 'react-popper';
+import { joinClassNames } from '../../../util/joinClassNames';
+import { IconButton } from '../../buttons/IconButton';
+import { ICON_BUTTON_APPEARANCE } from '../../../enums/buttonEnums';
+import { Icons } from '../../icons/Icons';
+import { menuTypes } from '../../../enums/menuTypes';
+import { useClickOutside } from '../../../hooks/useClickOutside';
+
+/** @typedef {import('@utahdts/utah-design-system').WebsiteMainMenu} WebsiteMainMenu */
+/** @typedef {import('@utahdts/utah-design-system').WebsiteMainMenuItem} WebsiteMainMenuItem */
+/** @typedef {import('@utahdts/utah-design-system').MenuTypes} MenuTypes  */
+
+/**
+ * @param {object} props
+ * @param {WebsiteMainMenu | WebsiteMainMenuItem} [props.currentMenuItem]
+ * @param {WebsiteMainMenuItem} props.menuItem
+ * @param {MenuTypes} [props.menuType]
+ * @returns {import('react').JSX.Element}
+ */
+export function MenuItemFlyout({
+  currentMenuItem,
+  menuItem,
+  menuType,
+}) {
+  const [isChildrenOpen, setIsChildrenOpen] = useImmer(false);
+  const referenceElement = useRef(/** @type {HTMLLIElement | null} */(null));
+  const popperRef = useRef(/** @type {HTMLDivElement | null} */(null));
+  const { styles, attributes } = usePopper(referenceElement.current, popperRef.current, { placement: 'right-start' });
+
+  const navLinkRef = useRef(/** @type {HTMLAnchorElement | null} */(null));
+  useClickOutside(popperRef, () => setIsChildrenOpen(false), !isChildrenOpen);
+
+  return (
+    <li className={menuType === menuTypes.VERTICAL ? 'vertical-menu__item' : 'menu-item'} ref={referenceElement}>
+      <span className={menuType === menuTypes.VERTICAL ? 'vertical-menu__title' : 'menu-item__title'}>
+        {
+          (!menuItem?.link || menuItem?.link?.includes('::'))
+            ? (
+              <button
+                aria-expanded={isChildrenOpen ? 'true' : 'false'}
+                aria-controls={`menu-item-${menuItem.id}-${menuItem.link}-popup`}
+                aria-haspopup="dialog"
+                className="menu-item__button-title"
+                id={`menu-item-${menuItem.id}-${menuItem.link}`}
+                onClick={() => setIsChildrenOpen((previouslyOpen) => !previouslyOpen)}
+                type="button"
+                title={menuItem.children ? 'Expand sub-menu' : ''}
+              >
+                <span className={menuType === menuTypes.VERTICAL ? 'vertical-menu__link-text' : 'menu__link-text'}>{menuItem.title}</span>
+                {menuItem.children ? <span className="utds-icon-before-chevron-right vertical-menu__chevron is-closed" aria-hidden="true" /> : null}
+              </button>
+            )
+            : (
+              <NavLink
+                className={(navData) => joinClassNames(
+                  menuType === menuTypes.VERTICAL ? 'vertical-menu__link-title' : 'menu-item__link-title',
+                  (currentMenuItem?.parentLinks?.includes(menuItem.link ?? '') || navData.isActive)
+                      && (currentMenuItem?.children?.length ? 'menu-item--selected_parent' : 'menu-item--selected')
+                )}
+                end
+                to={menuItem.link}
+                ref={navLinkRef}
+              >
+                {menuItem.title}
+              </NavLink>
+            )
+          }
+        {
+          (menuItem.children && menuItem?.link)
+            ? (
+              <IconButton
+                appearance={ICON_BUTTON_APPEARANCE.BORDERLESS}
+                aria-labelledby={`menu-item-${menuItem.id}-${menuItem.link}`}
+                aria-expanded={isChildrenOpen ? 'true' : 'false'}
+                className="menu-item__chevron"
+                onClick={() => setIsChildrenOpen((previouslyOpen) => !previouslyOpen)}
+                icon={<Icons.IconChevron />}
+                title="Expand sub-menu"
+              />
+            )
+            : null
+        }
+        <span className="menu-chiclet" />
+      </span>
+      {
+        menuItem.children
+          ? (
+            <div
+              aria-labelledby={`menu-item-${menuItem.id}-${menuItem.link}`}
+              className={joinClassNames(
+                'popup__wrapper',
+                isChildrenOpen ? 'popup__wrapper--visible' : 'popup__wrapper--hidden'
+              )}
+              id={`menu-item-${menuItem.id}-${menuItem.link}-popup`}
+              ref={popperRef}
+              style={styles.popper}
+              {...attributes.popper}
+            >
+              <div className="popup__content flyout-menu">
+                <ul role="menu" className={menuType === menuTypes.VERTICAL ? 'vertical-menu' : ''}>
+                  {menuItem.children?.map((menuItemChild) => (
+                    <MenuItemFlyout
+                      key={`menu-item__child__${menuItemChild.link}-${menuItemChild.title}}`}
+                      menuItem={menuItemChild}
+                      menuType={menuType}
+                    />
+                  ))}
+                </ul>
+              </div>
+            </div>
+          )
+          : null
+    }
+    </li>
+  );
+}

package/react/components/navigation/{MenuItem.jsx → items/MenuItemInline.jsx}

@@ -1,21 +1,28 @@
 import { useEffect, useLayoutEffect, useRef } from 'react';
 import { NavLink, useLocation } from 'react-router-dom';
 import { useImmer } from 'use-immer';
-import { ICON_BUTTON_APPEARANCE } from '../../enums/buttonEnums';
-import { joinClassNames } from '../../util/joinClassNames';
-import { IconButton } from '../buttons/IconButton';
-import { Icons } from '../icons/Icons';
+import { ICON_BUTTON_APPEARANCE } from '../../../enums/buttonEnums';
+import { joinClassNames } from '../../../util/joinClassNames';
+import { IconButton } from '../../buttons/IconButton';
+import { Icons } from '../../icons/Icons';
+import { menuTypes } from '../../../enums/menuTypes';
 
 /** @typedef {import('@utahdts/utah-design-system').WebsiteMainMenu} WebsiteMainMenu */
 /** @typedef {import('@utahdts/utah-design-system').WebsiteMainMenuItem} WebsiteMainMenuItem */
+/** @typedef {import('@utahdts/utah-design-system').MenuTypes} MenuTypes  */
 
 /**
  * @param {object} props
  * @param {WebsiteMainMenu | WebsiteMainMenuItem} [props.currentMenuItem]
  * @param {WebsiteMainMenuItem} props.menuItem
+ * @param {MenuTypes} [props.menuType]
  * @returns {import('react').JSX.Element}
  */
-export function MenuItem({ currentMenuItem, menuItem }) {
+export function MenuItemInline({
+  currentMenuItem,
+  menuItem,
+  menuType = menuTypes.VERTICAL,
+}) {
   const { pathname } = useLocation();
   // check if any of this menuItem's children are the currently open page/menuItem and if so, then keep this menuItem's children list open
   const [isChildrenOpen, setIsChildrenOpen] = useImmer(() => (
@@ -49,7 +56,7 @@ export function MenuItem({ currentMenuItem, menuItem }) {
   }
 
   return (
-    <li className="menu-item">
+    <li className={menuType === menuTypes.VERTICAL ? 'vertical-menu__item' : 'menu-item'}>
       <span className="menu-item__title">
         {/* === menu item title === */}
         {
@@ -68,6 +75,7 @@ export function MenuItem({ currentMenuItem, menuItem }) {
             : (
               <NavLink
                 className={(navData) => joinClassNames(
+                  'menu-item__link-title',
                   (currentMenuItem?.parentLinks?.includes(menuItem.link ?? '') || navData.isActive)
                   && (currentMenuItem?.children?.length ? 'menu-item--selected_parent' : 'menu-item--selected')
                 )}
@@ -106,11 +114,19 @@ export function MenuItem({ currentMenuItem, menuItem }) {
       {
         menuItem.children
           ? (
-            <ul className={joinClassNames('menu-item__sub-menu', isChildrenOpen ? 'menu-item__sub-menu--open' : '')} role="menu">
+            <ul
+              role="menu"
+              className={joinClassNames(
+                'menu-item__sub-menu',
+                menuType === menuTypes.VERTICAL ? 'vertical-menu' : '',
+                isChildrenOpen ? 'menu-item__sub-menu--open' : ''
+              )}
+            >
               {menuItem.children?.map((menuItemChild) => (
-                <MenuItem
+                <MenuItemInline
                   key={`menu-item__child__${menuItemChild.link}-${menuItemChild.title}}`}
                   menuItem={menuItemChild}
+                  menuType={menuType}
                 />
               ))}
             </ul>

package/react/components/navigation/items/MenuItemPlain.jsx

@@ -0,0 +1,63 @@
+import { NavLink } from 'react-router-dom';
+import { useRef } from 'react';
+import { joinClassNames } from '../../../util/joinClassNames';
+import { menuTypes } from '../../../enums/menuTypes';
+
+/** @typedef {import('@utahdts/utah-design-system').WebsiteMainMenu} WebsiteMainMenu */
+/** @typedef {import('@utahdts/utah-design-system').WebsiteMainMenuItem} WebsiteMainMenuItem */
+/** @typedef {import('@utahdts/utah-design-system').MenuTypes} MenuTypes  */
+
+/**
+ * @param {object} props
+ * @param {WebsiteMainMenu | WebsiteMainMenuItem} [props.currentMenuItem]
+ * @param {WebsiteMainMenuItem} props.menuItem
+ * @param {MenuTypes} [props.menuType]
+ * @returns {import('react').JSX.Element}
+ */
+export function MenuItemPlain({
+  currentMenuItem,
+  menuItem,
+  menuType,
+}) {
+  const navLinkRef = useRef(/** @type {HTMLAnchorElement | null} */(null));
+  return (
+    <li className={menuType === menuTypes.VERTICAL ? 'vertical-menu__item' : 'menu-item'}>
+      <span className={menuType === menuTypes.VERTICAL ? 'vertical-menu__title' : 'menu-item__title'}>
+        {
+            (!menuItem?.link || menuItem?.link?.includes('::'))
+              ? <span className={menuType === menuTypes.VERTICAL ? 'vertical-menu__title__plain' : 'menu-item__title__plain'}>{menuItem.title}</span>
+              : (
+                <NavLink
+                  className={(navData) => joinClassNames(
+                    menuType === menuTypes.VERTICAL ? 'vertical-menu__link-title' : 'menu-item__link-title',
+                    (currentMenuItem?.parentLinks?.includes(menuItem.link ?? '') || navData.isActive)
+                            && (currentMenuItem?.children?.length ? 'menu-item--selected_parent' : 'menu-item--selected')
+                  )}
+                  end
+                  to={menuItem.link}
+                  ref={navLinkRef}
+                >
+                  {menuItem.title}
+                </NavLink>
+              )
+        }
+        <span className="menu-chiclet" />
+      </span>
+      {
+          menuItem.children?.length
+            ? (
+              <ul role="menu" className={menuType === menuTypes.VERTICAL ? 'vertical-menu' : ''}>
+                {menuItem.children.map((menuItemChild) => (
+                  <MenuItemPlain
+                    key={`menu-item__child__${menuItemChild.link}-${menuItemChild.title}}`}
+                    menuItem={menuItemChild}
+                    menuType={menuType}
+                  />
+                ))}
+              </ul>
+            )
+            : null
+      }
+    </li>
+  );
+}

package/react/enums/menuTypes.js

@@ -0,0 +1,7 @@
+/** @typedef {import('@utahdts/utah-design-system').MenuTypes} MenuTypes */
+
+/** @enum {MenuTypes} */
+export const menuTypes = {
+  VERTICAL: /** @type {MenuTypes} */ ('vertical'),
+  HORIZONTAL: /** @type {MenuTypes} */ ('horizontal'),
+};

package/react/hooks/useDebounceFunc.js

@@ -30,7 +30,7 @@ export function useDebounceFunc(func, delay = 1000) {
           clearTimeout(timeoutRef.current);
           timeoutRef.current = window.setTimeout(
             () => {
-              func(lastVarArgsRef.current);
+              func(...(lastVarArgsRef.current || []));
               lastVarArgsRef.current = null;
               lastInvocationRef.current = NaN;
               resolve(varArgs);

package/react/hooks/useGlobalKeyEvent.js

@@ -3,7 +3,7 @@ import { useEffect, useRef, useState } from 'react';
 /**
  * @template KeyboardEventHandlerT
  * @param {object} params
- * @param {string} params.whichKeyCode
+ * @param {string} params.whichKeyCode https://www.w3.org/TR/uievents-key/#named-key-attribute-values
  * @param {import('react').KeyboardEventHandler<KeyboardEventHandlerT>} [params.onKeyDown]
  * @param {import('react').KeyboardEventHandler<KeyboardEventHandlerT>} [params.onKeyUp]
  * @returns {boolean}