@patternfly/react-core 4.276.0 → 4.276.2

package/src/components/Menu/examples/Menu.md

@@ -18,114 +18,177 @@ import AngleLeftIcon from '@patternfly/react-icons/dist/esm/icons/angle-left-ico
 
 ## Examples
 
-### Basic
+### Basic menus
+
+A menu may contain multiple variations of `<MenuItem>` components. The following example shows a few different states of menu items, where they may:
+
+- Use the `itemId` property to link to callbacks. In this example, the `onSelect` property logs information to the console when a menu item is selected. In practice, specific actions can be linked to `onSelect` callbacks.
+- Use the `to` property to direct users to other resources or webpages after selecting a menu item, and the `onClick` property to pass in a callback for specific menu items.
+- Use the `isDisabled` property to disable a menu item.
+- Use the `isPlain` property to remove the outer box shadow and style the menu plainly instead.
 
 ```ts file="MenuBasic.tsx"
 ```
 
 ### Danger menu item
 
+To indicate that a `<MenuItem>` is connected to a potentially destructive action, use the `isDanger` property. The "Delete" item in the following example demonstrates how danger items look.
+
 ```ts file="MenuDangerMenuItem.tsx"
 ```
 
 ### With icons
 
+Use the `icon` property to add a familiar icon before a `<MenuItem>` to accelerate text label recognition.
+
 ```ts file="MenuWithIcons.tsx"
 ```
 
-### With checkbox
+### With actions
+
+To connect a menu item to an action icon, add a `<MenuItemAction>` to a `<MenuItem>`, and use the `icon` property to load an easily recognizable icon.
 
-```ts file="./MenuWithCheckbox.tsx"
-```
+To trigger an action when any menu action icon is selected, pass a callback to the `onActionClick` property of the `<Menu>`. The following example logs to the console any time any action icon is selected.
 
-### Filtering with search input
+To trigger an action when a specific item's action icon is selected, pass in the `onClick` property to that `<MenuItemAction>`. The following example logs "clicked on code icon" to the console when the "code" icon is selected.
 
-```ts file="MenuFilteringWithSearchInput.tsx"
+```ts file="MenuWithActions.tsx"
 ```
 
 ### With links
 
+Use the `to` property to add a link to a `<MenuItem>` that directs users to a new page when the item is selected. Use the `isExternalLink` property when linking to external resources. This will annotate a menu item link with an external link icon when they navigate to the link or hover over it.
+
 ```ts file="MenuWithLinks.tsx"
 ```
 
-### With separator(s)
+### With descriptions
 
-```ts file="MenuWithSeparators.tsx"
+Use the `description` property to add short descriptive text below any menu item that needs additional context.
+
+```ts file="MenuWithDescription.tsx"
 ```
 
-### With titled groups
+### Item checkbox
 
-```ts file="MenuWithTitledGroups.tsx"
+Use the `hasCheck` property to add a checkbox to a `<MenuItem>`. Use the `isSelected` property to indicate when a `<MenuItem>` is selected.
+
+```ts file="./MenuWithCheckbox.tsx" isBeta
 ```
 
-### With description
+### Menu footer
 
-```ts file="MenuWithDescription.tsx"
+Add a `<MenuFooter>` that contains separate, but related actions at the bottom of a menu.
+
+```ts file="MenuWithFooter.tsx"
 ```
 
-### With actions
+### Separated items
 
-```ts file="MenuWithActions.tsx"
+Use a [divider](/components/divider) to visually separate `<MenuContent>`. Use the `component` property to specify the type of divider component to use.
+
+```ts file="MenuWithSeparators.tsx"
+```
+
+### Titled groups of items
+
+Add a `<MenuGroup>` to organize `<MenuContent>` and use the `label` property to title a group of menu items. Use the `labelHeadingLevel` property to assign a heading level to the menu group label.
+
+```ts file="MenuWithTitledGroups.tsx"
 ```
 
 ### With favorites
 
+The following menu example allows users to favorite menu items, an action that duplicates a menu item and places it in a separate group at the top of the menu. The `isFavorited` property identifies items that a user has favorited.
+
 ```ts file="MenuWithFavorites.tsx"
 ```
 
-### Option single select
+### Filtering with search input
+
+A [search input](/components/search-input) component can be placed within `<MenuInput>` to render a search input at the top of the menu. In the following example, the `onChange` property of the text input is passed a callback that filters menu items as a user types.
+
+```ts file="MenuFilteringWithSearchInput.tsx"
+```
+
+### Option single select menu
+
+The following example demonstrates a single option select menu that persists a selected menu item. Use the `selected` property on the `<Menu>` to label a selected item with a checkmark. You can also use the `isSelected` property on a `<MenuItem>` to indicate that it is selected.
+
+You must also use the `role` property on the `<Menu>` with a value of `"listbox"` when using a non-checkbox select menu.
 
 ```ts file="MenuOptionSingleSelect.tsx"
 ```
 
-### Option multi select
+### Option multi select menu
+
+To persist multiple selections that a user makes, use a multiple option select menu. To enable multi select, pass an array containing each selected `itemId` to the `selected` property on the `<Menu>`, and pass the `isAriaMultiselectable` property on the `<MenuList>`.
+
+Similar to a single select menu, you must also pass `role="listbox"` to the `<Menu>`.
 
 ```ts file="MenuOptionMultiSelect.tsx"
 ```
 
-### With drilldown
+### Scrollable menus
 
-```ts file="./MenuWithDrilldown.tsx" isBeta
+Use the `isScrollable` property to make a long `<Menu>` scrollable and visually condensed.
+
+```ts file="MenuScrollable.tsx"
 ```
 
-### With drilldown - initial drill in state
+### Scrollable menu with custom height
 
-To render an initially drilled in menu, the `menuDrilledIn`, `drilldownPath`, and `activeMenu` states must be set to an initial state. The `menuHeights` state must also be set, defining the height of the root menu. The `setHeight` function passed into the `onGetMenuHeight` property must also account for updating heights, other than the root menu, as menus drill in and out of view.
+Adjust the visual size of a scrollable menu by using the `menuHeight` property within `<MenuContent>`. This example adjusts the height to 200px.
 
-```ts file="./MenuWithDrilldownInitialState.tsx" isBeta
+```ts file="MenuScrollableCustomMenuHeight.tsx"
 ```
 
-### With drilldown - submenu functions
+### With view more
 
-```ts file="./MenuWithDrilldownSubmenuFunctions.tsx" isBeta
-```
+If you want to initially render only a certain number of menu items within a large menu, you can add a "view more" menu item with a callback passed into its `onClick` property that will render additional menu items.
 
-### With drilldown breadcrumbs
+In this example, 3 additional menu items are revealed each time the "view more" option is selected, with a loading icon simulating a network call to fetch more items. After all items are visible, the "view more" link disappears.
 
-```ts file="MenuWithDrilldownBreadcrumbs.tsx" isBeta
+```ts file="MenuWithViewMore.tsx"
 ```
 
-### With drilldown and inline filter
+### With drilldown
 
-```ts file="MenuFilterDrilldown.tsx"
+Use a drilldown menu to contain different levels of menu items. When a parent menu item (an item that has a submenu of children) is selected, the menu is replaced with the children items.
+
+- To indicate that a menu contains a drilldown, use the `containsDrilldown` property.
+- To indicate the path of drilled-in menu item ids, use the `drilldownItemPath` property.
+- Pass in an array of drilled-in menus with the `drilledInMenus` property.
+- Use the `onDrillIn` and `onDrillOut` properties to contain callbacks for drilling into and drilling out of a submenu, respectively.
+- To account for updated heights as menus drill in and out of use, use the `onGetMenuHeight` property. When starting from a drilled-in state, the `onGetMenuHeight` property must define the height of the root menu.
+
+```ts file="./MenuWithDrilldown.tsx" isBeta
 ```
 
-### Scrollable
+### Initially drilled-in menu
 
-```ts file="MenuScrollable.tsx"
+To render an initially drilled-in menu, the `drilldownItemPath`, `drilledInMenus`, and `activeMenu` properties must be set to default values.
+
+```ts file="./MenuWithDrilldownInitialState.tsx" isBeta
 ```
 
-### Scrollable with custom menu height
+### With drilldown - submenu functions
 
-```ts file="MenuScrollableCustomMenuHeight.tsx"
+For added flexibility with large menus, you may create a menu by passing a function to `drilldownMenu`. This approach allows you to create menu items dynamically, rather than creating everything up front.
+
+```ts file="./MenuWithDrilldownSubmenuFunctions.tsx" isBeta
 ```
 
-### With footer
+### With drilldown breadcrumbs
 
-```ts file="MenuWithFooter.tsx"
+Use [breadcrumbs](/components/breadcrumb) when a drilldown menu has more than 2 levels to offer users better navigation.
+
+To control the height of a menu, use the `maxMenuHeight` property. Selecting the "Set max menu height" checkbox in the following example sets the menu height to "100px" and makes the menu scrollable.
+
+```ts file="MenuWithDrilldownBreadcrumbs.tsx" isBeta
 ```
 
-### With view more
+### With drilldown and inline filter
 
-```ts file="MenuWithViewMore.tsx"
+```ts file="MenuFilterDrilldown.tsx"
 ```

package/src/components/Menu/examples/MenuOptionMultiSelect.tsx

@@ -15,9 +15,9 @@ export const MenuOptionMultiSelect: React.FunctionComponent = () => {
   };
 
   return (
-    <Menu onSelect={onSelect} activeItemId={0} selected={selectedItems}>
+    <Menu role="listbox" onSelect={onSelect} activeItemId={0} selected={selectedItems}>
       <MenuContent>
-        <MenuList>
+        <MenuList isAriaMultiselectable aria-label="Menu multi select example">
           <MenuItem itemId={0}>Option 1</MenuItem>
           <MenuItem itemId={1}>Option 2</MenuItem>
           <MenuItem icon={<TableIcon aria-hidden />} itemId={2}>

package/src/components/Menu/examples/MenuOptionSingleSelect.tsx

@@ -12,9 +12,9 @@ export const MenuOptionSingleSelect: React.FunctionComponent = () => {
   };
 
   return (
-    <Menu onSelect={onSelect} activeItemId={activeItem} selected={selectedItem}>
+    <Menu role="listbox" onSelect={onSelect} activeItemId={activeItem} selected={selectedItem}>
       <MenuContent>
-        <MenuList>
+        <MenuList aria-label="Menu single select example">
           <MenuItem itemId={0}>Option 1</MenuItem>
           <MenuItem itemId={1}>Option 2</MenuItem>
           <MenuItem icon={<TableIcon aria-hidden />} itemId={2}>

package/src/next/components/Dropdown/Dropdown.tsx

@@ -58,28 +58,27 @@ const DropdownBase: React.FunctionComponent<DropdownProps> = ({
   const menuRef = (innerRef as React.RefObject<HTMLDivElement>) || localMenuRef;
   React.useEffect(() => {
     const handleMenuKeys = (event: KeyboardEvent) => {
-      if (!isOpen && toggleRef.current?.contains(event.target as Node)) {
-        // toggle was clicked open, focus on first menu item
-        if (event.key === 'Enter') {
-          setTimeout(() => {
-            const firstElement = menuRef.current.querySelector('li > button:not(:disabled)');
-            firstElement && (firstElement as HTMLElement).focus();
-          }, 0);
-        }
-      }
       // Close the menu on tab or escape if onOpenChange is provided
       if (
         (isOpen && onOpenChange && menuRef.current?.contains(event.target as Node)) ||
         toggleRef.current?.contains(event.target as Node)
       ) {
         if (event.key === 'Escape' || event.key === 'Tab') {
-          onOpenChange(!isOpen);
+          onOpenChange(false);
           toggleRef.current?.focus();
         }
       }
     };
 
-    const handleClickOutside = (event: MouseEvent) => {
+    const handleClick = (event: MouseEvent) => {
+      // toggle was clicked open via keyboard, focus on first menu item
+      if (isOpen && toggleRef.current?.contains(event.target as Node) && event.detail === 0) {
+        setTimeout(() => {
+          const firstElement = menuRef?.current?.querySelector('li button:not(:disabled),li input:not(:disabled)');
+          firstElement && (firstElement as HTMLElement).focus();
+        }, 0);
+      }
+
       // If the event is not on the toggle and onOpenChange callback is provided, close the menu
       if (isOpen && onOpenChange && !toggleRef?.current?.contains(event.target as Node)) {
         if (isOpen && !menuRef.current?.contains(event.target as Node)) {
@@ -89,11 +88,11 @@ const DropdownBase: React.FunctionComponent<DropdownProps> = ({
     };
 
     window.addEventListener('keydown', handleMenuKeys);
-    window.addEventListener('click', handleClickOutside);
+    window.addEventListener('click', handleClick);
 
     return () => {
       window.removeEventListener('keydown', handleMenuKeys);
-      window.removeEventListener('click', handleClickOutside);
+      window.removeEventListener('click', handleClick);
     };
   }, [isOpen, menuRef, onOpenChange]);
 

package/src/next/components/Select/Select.tsx

@@ -28,6 +28,8 @@ export interface SelectProps extends MenuProps, OUIAProps {
   innerRef?: React.Ref<HTMLDivElement>;
   /** z-index of the select menu */
   zIndex?: number;
+  /** @beta Determines the accessible role of the select. For a checkbox select pass in "menu". */
+  role?: string;
 }
 
 const SelectBase: React.FunctionComponent<SelectProps & OUIAProps> = ({
@@ -42,6 +44,7 @@ const SelectBase: React.FunctionComponent<SelectProps & OUIAProps> = ({
   minWidth,
   innerRef,
   zIndex = 9999,
+  role = 'listbox',
   ...props
 }: SelectProps & OUIAProps) => {
   const localMenuRef = React.useRef<HTMLDivElement>();
@@ -51,28 +54,27 @@ const SelectBase: React.FunctionComponent<SelectProps & OUIAProps> = ({
   const menuRef = (innerRef as React.RefObject<HTMLDivElement>) || localMenuRef;
   React.useEffect(() => {
     const handleMenuKeys = (event: KeyboardEvent) => {
-      if (!isOpen && toggleRef.current?.contains(event.target as Node)) {
-        // toggle was clicked open, focus on first menu item
-        if (event.key === 'Enter' || event.key === 'Space') {
-          setTimeout(() => {
-            const firstElement = menuRef?.current?.querySelector('li button:not(:disabled),li input:not(:disabled)');
-            firstElement && (firstElement as HTMLElement).focus();
-          }, 0);
-        }
-      }
       // Close the menu on tab or escape if onOpenChange is provided
       if (
         (isOpen && onOpenChange && menuRef.current?.contains(event.target as Node)) ||
         toggleRef.current?.contains(event.target as Node)
       ) {
         if (event.key === 'Escape' || event.key === 'Tab') {
-          onOpenChange(!isOpen);
+          onOpenChange(false);
           toggleRef.current?.focus();
         }
       }
     };
 
-    const handleClickOutside = (event: MouseEvent) => {
+    const handleClick = (event: MouseEvent) => {
+      // toggle was clicked open via keyboard, focus on first menu item
+      if (isOpen && toggleRef.current?.contains(event.target as Node) && event.detail === 0) {
+        setTimeout(() => {
+          const firstElement = menuRef?.current?.querySelector('li button:not(:disabled),li input:not(:disabled)');
+          firstElement && (firstElement as HTMLElement).focus();
+        }, 0);
+      }
+
       // If the event is not on the toggle and onOpenChange callback is provided, close the menu
       if (isOpen && onOpenChange && !toggleRef?.current?.contains(event.target as Node)) {
         if (isOpen && !menuRef.current?.contains(event.target as Node)) {
@@ -82,16 +84,17 @@ const SelectBase: React.FunctionComponent<SelectProps & OUIAProps> = ({
     };
 
     window.addEventListener('keydown', handleMenuKeys);
-    window.addEventListener('click', handleClickOutside);
+    window.addEventListener('click', handleClick);
 
     return () => {
       window.removeEventListener('keydown', handleMenuKeys);
-      window.removeEventListener('click', handleClickOutside);
+      window.removeEventListener('click', handleClick);
     };
   }, [isOpen, menuRef, onOpenChange]);
 
   const menu = (
     <Menu
+      role={role}
       className={css(className)}
       ref={menuRef}
       onSelect={(event, itemId) => onSelect(event, itemId)}

package/src/next/components/Select/SelectList.tsx

@@ -7,14 +7,19 @@ export interface SelectListProps extends MenuListProps {
   children: React.ReactNode;
   /** Classes applied to root element of select list */
   className?: string;
+  /** @beta Indicates to assistive technologies whether more than one item can be selected
+   * for a non-checkbox select.
+   */
+  isAriaMultiselectable?: boolean;
 }
 
 export const SelectList: React.FunctionComponent<MenuListProps> = ({
   children,
   className,
+  isAriaMultiselectable = false,
   ...props
 }: SelectListProps) => (
-  <MenuList className={css(className)} {...props}>
+  <MenuList isAriaMultiselectable={isAriaMultiselectable} className={css(className)} {...props}>
     {children}
   </MenuList>
 );

package/src/next/components/Select/examples/SelectCheckbox.tsx

@@ -40,6 +40,7 @@ export const SelectCheckbox: React.FunctionComponent = () => {
 
   return (
     <Select
+      role="menu"
       id="checkbox-select"
       ref={menuRef}
       isOpen={isOpen}

package/src/next/components/Select/examples/SelectMultiTypeahead.tsx

@@ -179,7 +179,7 @@ export const SelectMultiTypeahead: React.FunctionComponent = () => {
       onOpenChange={() => setIsOpen(false)}
       toggle={toggle}
     >
-      <SelectList>
+      <SelectList isAriaMultiselectable>
         {selectOptions.map((option, index) => (
           <SelectOption
             key={option.itemId || option.children}