feat(menu): adds support for link items (#648)

geotrev · web-flow · commit cfa0aa1eb420 · 2024-07-01T11:08:33.000-05:00
diff --git a/.storybook/preview.js b/.storybook/preview.js
@@ -31,7 +31,7 @@ export const parameters = {
 };
 
 const GlobalStyle = createGlobalStyle`
-  :focus {
+  :focus-visible {
     outline-color: ${p => getColor('primaryHue', 600, p.theme)};
   }
 `;
diff --git a/packages/menu/README.md b/packages/menu/README.md
@@ -61,7 +61,8 @@ const Menu = () => {
   const items = [
     { value: 'value-1', label: 'One' },
     { value: 'value-2', label: 'Two' },
-    { value: 'value-3', label: 'Three' }
+    { value: 'value-3', label: 'Three', href: '#0' },
+    { value: 'value-4', label: 'Four' }
   ];
 
   return (
@@ -70,11 +71,17 @@ const Menu = () => {
         <>
           <button {...getTriggerProps()}>Menu</button>
           <ul {...getMenuProps()} style={{ visibility: isExpanded ? 'visible' : 'hidden' }}>
-            {items.map(item => (
-              <li key={item.value} {...getItemProps({ item })}>
-                {item.label}
-              </li>
-            ))}
+            {items.map(item =>
+              item.href ? (
+                <li key={item.value} role="none">
+                  <a {...getItemProps({ item })}>{item.label}</a>
+                </li>
+              ) : (
+                <li key={item.value} {...getItemProps({ item })}>
+                  {item.label}
+                </li>
+              )
+            )}
           </ul>
         </>
       )}
diff --git a/packages/menu/demo/stories/MenuStory.tsx b/packages/menu/demo/stories/MenuStory.tsx
@@ -5,7 +5,7 @@
  * found at http://www.apache.org/licenses/LICENSE-2.0.
  */
 
-import React, { useRef } from 'react';
+import React, { AnchorHTMLAttributes, LiHTMLAttributes, useRef } from 'react';
 import { StoryFn } from '@storybook/react';
 import classNames from 'classnames';
 import {
@@ -33,23 +33,49 @@ type MenuItemProps = {
   isSelected?: boolean;
 };
 
-const Item = ({ item, getItemProps, focusedValue, isSelected }: MenuItemProps) => (
-  <li
-    className={classNames({
-      'bg-blue-100': !item.disabled && focusedValue === item.value,
-      'text-grey-400': item.disabled,
-      'cursor-pointer': !item.disabled,
-      'cursor-default': item.disabled
-    })}
-    {...getItemProps({ item })}
-  >
-    <span className="inline-flex justify-center items-center w-4">
-      {item?.type === 'radio' && isSelected && '•'}
-      {item?.type === 'checkbox' && isSelected && '✓'}
-    </span>
-    {item.label || item.value}
-  </li>
-);
+const Item = ({ item, getItemProps, focusedValue, isSelected }: MenuItemProps) => {
+  const itemProps = getItemProps({ item });
+
+  const itemChildren = (
+    <>
+      <span className="inline-flex justify-center items-center w-4">
+        {item?.type === 'radio' && isSelected && '•'}
+        {item?.type === 'checkbox' && isSelected && '✓'}
+      </span>
+      {item.label || item.value}
+    </>
+  );
+
+  return (
+    <li
+      className={classNames('flex', {
+        'bg-blue-100': !item.disabled && focusedValue === item.value,
+        'text-grey-400': item.disabled,
+        'cursor-pointer': !item.disabled,
+        'cursor-default': item.disabled
+      })}
+      role={itemProps.href ? 'none' : undefined}
+      {...(!itemProps.href && (itemProps as LiHTMLAttributes<HTMLLIElement>))}
+    >
+      {itemProps.href ? (
+        <a
+          {...(itemProps as AnchorHTMLAttributes<HTMLAnchorElement>)}
+          className="w-full rounded-sm outline-offset-0 transition-none border-width-none"
+        >
+          {itemChildren}
+          {item.isExternal && (
+            <>
+              <span aria-hidden="true"> ↗</span>
+              <span className="sr-only">(opens in new window)</span>
+            </>
+          )}
+        </a>
+      ) : (
+        itemChildren
+      )}
+    </li>
+  );
+};
 
 const Component = ({
   items,
@@ -66,7 +92,9 @@ const Component = ({
 
   return (
     <div className="relative">
-      <button {...getTriggerProps()}>Produce</button>
+      <button className="px-2 py-1" type="button" {...getTriggerProps()}>
+        Produce
+      </button>
 
       <ul
         className={classNames('border border-grey-400 border-solid w-32 absolute', {
diff --git a/packages/menu/demo/stories/data.ts b/packages/menu/demo/stories/data.ts
@@ -12,7 +12,13 @@ export const ITEMS: MenuItem[] = [
   { value: 'plant-02', label: 'Hydrangea' },
   { value: 'separator-01', separator: true },
   { value: 'plant-03', label: 'Violet' },
-  { value: 'plant-04', label: 'Succulent' },
+  {
+    value: 'plant-04',
+    label: 'Aloe Vera',
+    href: 'https://en.wikipedia.org/wiki/Aloe_vera',
+    isExternal: false
+  },
+  { value: 'plant-05', label: 'Succulent' },
   {
     label: 'Choose favorites',
     items: [
diff --git a/packages/menu/src/MenuContainer.spec.tsx b/packages/menu/src/MenuContainer.spec.tsx
@@ -254,6 +254,16 @@ describe('MenuContainer', () => {
       expect(menu).not.toBeVisible();
     });
 
+    it('applies external anchor attributes', () => {
+      const { getByTestId } = render(
+        <TestMenu items={[{ value: 'item', href: '#0', isExternal: true }]} />
+      );
+      const menu = getByTestId('menu');
+
+      expect(menu.firstChild).toHaveAttribute('target', '_blank');
+      expect(menu.firstChild).toHaveAttribute('rel', 'noopener noreferrer');
+    });
+
     describe('focus', () => {
       describe('trigger', () => {
         it('focuses first item on arrow keydown', async () => {
@@ -1187,4 +1197,22 @@ describe('MenuContainer', () => {
       });
     });
   });
+
+  describe('error handling', () => {
+    it.each([
+      { key: 'isNext', isNext: true },
+      { key: 'isPrevious', isPrevious: true }
+    ])("throws when anchor item uses '$key'", itemProps => {
+      expect(() =>
+        render(<TestMenu items={[{ value: 'test', href: '#0', ...itemProps }]} />)
+      ).toThrow();
+    });
+
+    it.each<'radio' | 'checkbox'>(['radio', 'checkbox'])(
+      "throws when anchor item is '%s' type",
+      type => {
+        expect(() => render(<TestMenu items={[{ value: 'test', href: '#0', type }]} />)).toThrow();
+      }
+    );
+  });
 });
diff --git a/packages/menu/src/types.ts b/packages/menu/src/types.ts
@@ -13,6 +13,8 @@ export interface ISelectedItem {
   name?: string;
   type?: 'radio' | 'checkbox';
   disabled?: boolean;
+  href?: string;
+  isExternal?: boolean;
 }
 
 export interface IMenuItemBase extends ISelectedItem {
diff --git a/packages/menu/src/useMenu.ts b/packages/menu/src/useMenu.ts
@@ -27,7 +27,8 @@ import {
   isValidItem,
   StateChangeTypes,
   stateReducer,
-  toMenuItemKeyDownType
+  toMenuItemKeyDownType,
+  triggerLink
 } from './utils';
 import {
   MenuItem,
@@ -124,7 +125,8 @@ export const useMenu = <T extends HTMLElement = HTMLElement, M extends HTMLEleme
     values,
     direction: 'vertical',
     selectedValue: focusedValue || uncontrolledFocusedValue,
-    focusedValue: focusedValue || uncontrolledFocusedValue
+    focusedValue: focusedValue || uncontrolledFocusedValue,
+    allowDefaultOnSelect: true
   });
 
   /**
@@ -242,6 +244,27 @@ export const useMenu = <T extends HTMLElement = HTMLElement, M extends HTMLEleme
     [controlledSelectedItems]
   );
 
+  const anchorItemError = ({ isNext, isPrevious, type, value }: IMenuItemBase) => {
+    let invariantKey: string;
+
+    if (isNext) {
+      invariantKey = 'isNext';
+    } else if (isPrevious) {
+      invariantKey = 'isPrevious';
+    } else {
+      invariantKey = type!;
+    }
+
+    const invariantType = {
+      isNext: 'isNext',
+      isPrevious: 'isPrevious',
+      radio: 'radio',
+      checkbox: 'checkbox'
+    }[invariantKey];
+
+    throw new Error(`Error: expected useMenu anchor item '${value}' to not use '${invariantType}'`);
+  };
+
   // Event
 
   const handleTriggerClick = useCallback(
@@ -425,6 +448,16 @@ export const useMenu = <T extends HTMLElement = HTMLElement, M extends HTMLEleme
           ...(nextSelection && { selectedItems: nextSelection })
         };
 
+        if (item.href) {
+          if (key === KEYS.SPACE) {
+            event.preventDefault();
+
+            triggerLink(event.target as HTMLAnchorElement, environment || window);
+          }
+        } else {
+          event.preventDefault();
+        }
+
         if (!isTransitionItem) {
           focusTriggerRef.current = true;
         }
@@ -438,6 +471,8 @@ export const useMenu = <T extends HTMLElement = HTMLElement, M extends HTMLEleme
         }
 
         if (changeType) {
+          event.preventDefault();
+
           changes = { value: item.value };
         }
       } else if (key === KEYS.LEFT) {
@@ -450,9 +485,13 @@ export const useMenu = <T extends HTMLElement = HTMLElement, M extends HTMLEleme
         }
 
         if (changeType) {
+          event.preventDefault();
+
           changes = { value: item.value };
         }
       } else if (isVerticalArrowKeys || isJumpKey || isAlphanumericChar) {
+        event.preventDefault();
+
         changeType = isAlphanumericChar
           ? StateChangeTypes.MenuItemKeyDown
           : StateChangeTypes[toMenuItemKeyDownType(key)];
@@ -470,7 +509,6 @@ export const useMenu = <T extends HTMLElement = HTMLElement, M extends HTMLEleme
       }
 
       if (changeType) {
-        event.preventDefault();
         event.stopPropagation();
 
         const transitionNext = changeType.includes('next');
@@ -497,6 +535,7 @@ export const useMenu = <T extends HTMLElement = HTMLElement, M extends HTMLEleme
       isFocusedValueControlled,
       isSelectedItemsControlled,
       focusTriggerRef,
+      environment,
       getNextFocusedValue,
       getSelectedItems,
       onChange
@@ -700,6 +739,8 @@ export const useMenu = <T extends HTMLElement = HTMLElement, M extends HTMLEleme
         type,
         name,
         value,
+        href,
+        isExternal,
         isNext = false,
         isPrevious = false,
         label = value
@@ -729,12 +770,26 @@ export const useMenu = <T extends HTMLElement = HTMLElement, M extends HTMLEleme
         'aria-checked': selected,
         'aria-disabled': itemDisabled,
         role: itemRole === null ? undefined : itemRole,
+        href,
         onClick,
         onKeyDown,
         onMouseEnter,
         ...other
       };
 
+      if (href && isExternal) {
+        elementProps.target = '_blank';
+        elementProps.rel = 'noopener noreferrer';
+      }
+
+      /**
+       * Validation
+       */
+
+      if (href && (isNext || isPrevious || type)) {
+        anchorItemError(item);
+      }
+
       if (itemDisabled) {
         return elementProps;
       }
diff --git a/packages/menu/src/utils.ts b/packages/menu/src/utils.ts
@@ -9,6 +9,16 @@ import { Reducer } from 'react';
 import { KEYS } from '@zendeskgarden/container-utilities';
 import { MenuItem, IMenuItemBase, IMenuItemSeparator, ISelectedItem } from './types';
 
+export const triggerLink = (element: HTMLAnchorElement, view: Window) => {
+  const event = new MouseEvent('click', {
+    bubbles: true,
+    cancelable: true,
+    view
+  });
+
+  element.dispatchEvent(event);
+};
+
 export const StateChangeTypes: Record<string, string> = {
   FnSetStateRefs: 'fn:setStateRefs',
   FnMenuTransitionFinish: 'fn:menuTransitionFinish',
diff --git a/packages/selection/src/types.ts b/packages/selection/src/types.ts
@@ -22,6 +22,8 @@ export interface IUseSelectionProps<Value> {
   selectedValue?: Value;
   /** Sets controlled value focus */
   focusedValue?: Value;
+  /** Allows `preventDefault` to be called on selection */
+  allowDefaultOnSelect?: boolean;
   /**
    * Handles controlled value selection
    *
diff --git a/packages/selection/src/useSelection.ts b/packages/selection/src/useSelection.ts
@@ -27,6 +27,7 @@ export const useSelection = <Value>({
   rtl,
   selectedValue,
   focusedValue,
+  allowDefaultOnSelect = false,
   onSelect,
   onFocus
 }: IUseSelectionProps<Value>): IUseSelectionReturnValue<Value> => {
@@ -199,7 +200,7 @@ export const useSelection = <Value>({
           onSelect && onSelect(value);
           !isSelectedValueControlled && dispatch({ type: 'KEYBOARD_SELECT', payload: value });
 
-          event.preventDefault();
+          !allowDefaultOnSelect && event.preventDefault();
         }
       }
     };

Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@ export const parameters = {`
`31`	`31`	`};`
`32`	`32`
`33`	`33`	const GlobalStyle = createGlobalStyle`
`34`		`- :focus {`
	`34`	`+ :focus-visible {`
`35`	`35`	`outline-color: ${p => getColor('primaryHue', 600, p.theme)};`
`36`	`36`	`}`
`37`	`37`	`;
Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,8 @@ export interface ISelectedItem {`
`13`	`13`	`name?: string;`
`14`	`14`	`type?: 'radio' \| 'checkbox';`
`15`	`15`	`disabled?: boolean;`
	`16`	`+ href?: string;`
	`17`	`+ isExternal?: boolean;`
`16`	`18`	`}`
`17`	`19`
`18`	`20`	`export interface IMenuItemBase extends ISelectedItem {`
Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,8 @@ export interface IUseSelectionProps<Value> {`
`22`	`22`	`selectedValue?: Value;`
`23`	`23`	`/** Sets controlled value focus */`
`24`	`24`	`focusedValue?: Value;`
	`25`	+ /** Allows `preventDefault` to be called on selection */
	`26`	`+ allowDefaultOnSelect?: boolean;`
`25`	`27`	`/**`
`26`	`28`	`* Handles controlled value selection`
`27`	`29`	`*`