@patternfly/react-core 5.0.0-alpha.107 → 5.0.0-alpha.109

package/src/components/Select/Select.tsx

@@ -1,9 +1,35 @@
 import React from 'react';
 import { css } from '@patternfly/react-styles';
 import { Menu, MenuContent, MenuProps } from '../Menu';
-import { Popper, PopperProps } from '../../helpers/Popper/Popper';
+import { Popper } from '../../helpers/Popper/Popper';
 import { getOUIAProps, OUIAProps, getDefaultOUIAId } from '../../helpers';
 
+export interface SelectPopperProps {
+  /** Vertical direction of the popper. If enableFlip is set to true, this will set the initial direction before the popper flips. */
+  direction?: 'up' | 'down';
+  /** Horizontal position of the popper */
+  position?: 'right' | 'left' | 'center';
+  /** Custom width of the popper. If the value is "trigger", it will set the width to the select toggle's width */
+  width?: string | 'trigger';
+  /** Minimum width of the popper. If the value is "trigger", it will set the min width to the select toggle's width */
+  minWidth?: string | 'trigger';
+  /** Maximum width of the popper. If the value is "trigger", it will set the max width to the select toggle's width */
+  maxWidth?: string | 'trigger';
+  /** Enable to flip the popper when it reaches the boundary */
+  enableFlip?: boolean;
+}
+
+export interface SelectToggleProps {
+  /**  Select toggle node. */
+  toggleNode: React.ReactNode;
+  /** Reference to the toggle. */
+  toggleRef?: React.RefObject<HTMLButtonElement>;
+}
+
+/**
+ * See the Menu documentation for additional props that may be passed.
+ */
+
 export interface SelectProps extends MenuProps, OUIAProps {
   /** Anything which can be rendered in a select */
   children?: React.ReactNode;
@@ -13,13 +39,17 @@ export interface SelectProps extends MenuProps, OUIAProps {
   isOpen?: boolean;
   /** Single itemId for single select menus, or array of itemIds for multi select. You can also specify isSelected on the SelectOption. */
   selected?: any | any[];
-  /** Renderer for a custom select toggle. Forwards a ref to the toggle. */
-  toggle: (toggleRef: React.RefObject<any>) => React.ReactNode;
+  /** Select toggle. The toggle should either be a renderer function which forwards the given toggle ref, or a direct ReactNode that should be passed along with the toggleRef property. */
+  toggle: SelectToggleProps | ((toggleRef: React.RefObject<any>) => React.ReactNode);
+  /** Flag indicating the toggle should be focused after a selection. If this use case is too restrictive, the optional toggleRef property with a node toggle may be used to control focus. */
+  shouldFocusToggleOnSelect?: boolean;
   /** Function callback when user selects an option. */
   onSelect?: (event?: React.MouseEvent<Element, MouseEvent>, itemId?: string | number) => void;
   /** Callback to allow the select component to change the open state of the menu.
-   * Triggered by clicking outside of the menu, or by pressing either tab or escape. */
+   * Triggered by clicking outside of the menu, or by pressing any keys specificed in onOpenChangeKeys. */
   onOpenChange?: (isOpen: boolean) => void;
+  /** @beta Keys that trigger onOpenChange, defaults to tab and escape. It is highly recommended to include Escape in the array, while Tab may be omitted if the menu contains non-menu items that are focusable. */
+  onOpenChangeKeys?: string[];
   /** Indicates if the select should be without the outer box-shadow */
   isPlain?: boolean;
   /** @hide Forwarded ref */
@@ -29,7 +59,7 @@ export interface SelectProps extends MenuProps, OUIAProps {
   /** @beta Determines the accessible role of the select. For a checkbox select pass in "menu". */
   role?: string;
   /** Additional properties to pass to the popper */
-  popperProps?: Partial<PopperProps>;
+  popperProps?: SelectPopperProps;
 }
 
 const SelectBase: React.FunctionComponent<SelectProps & OUIAProps> = ({
@@ -39,7 +69,9 @@ const SelectBase: React.FunctionComponent<SelectProps & OUIAProps> = ({
   isOpen,
   selected,
   toggle,
+  shouldFocusToggleOnSelect = false,
   onOpenChange,
+  onOpenChangeKeys = ['Escape', 'Tab'],
   isPlain,
   innerRef,
   zIndex = 9999,
@@ -48,18 +80,24 @@ const SelectBase: React.FunctionComponent<SelectProps & OUIAProps> = ({
   ...props
 }: SelectProps & OUIAProps) => {
   const localMenuRef = React.useRef<HTMLDivElement>();
-  const toggleRef = React.useRef<HTMLButtonElement>();
-  const containerRef = React.useRef<HTMLDivElement>();
+  const localToggleRef = React.useRef<HTMLButtonElement>();
 
   const menuRef = (innerRef as React.RefObject<HTMLDivElement>) || localMenuRef;
+  const toggleRef =
+    typeof toggle === 'function' || (typeof toggle !== 'function' && !toggle.toggleRef)
+      ? localToggleRef
+      : (toggle?.toggleRef as React.RefObject<HTMLButtonElement>);
+
   React.useEffect(() => {
     const handleMenuKeys = (event: KeyboardEvent) => {
       // 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)
+        isOpen &&
+        onOpenChange &&
+        (menuRef.current?.contains(event.target as Node) || toggleRef.current?.contains(event.target as Node))
       ) {
-        if (event.key === 'Escape' || event.key === 'Tab') {
+        if (onOpenChangeKeys.includes(event.key)) {
+          event.preventDefault();
           onOpenChange(false);
           toggleRef.current?.focus();
         }
@@ -90,14 +128,17 @@ const SelectBase: React.FunctionComponent<SelectProps & OUIAProps> = ({
       window.removeEventListener('keydown', handleMenuKeys);
       window.removeEventListener('click', handleClick);
     };
-  }, [isOpen, menuRef, onOpenChange]);
+  }, [isOpen, menuRef, toggleRef, onOpenChange, onOpenChangeKeys]);
 
   const menu = (
     <Menu
       role={role}
       className={css(className)}
       ref={menuRef}
-      onSelect={(event, itemId) => onSelect && onSelect(event, itemId)}
+      onSelect={(event, itemId) => {
+        onSelect && onSelect(event, itemId);
+        shouldFocusToggleOnSelect && toggleRef.current.focus();
+      }}
       isPlain={isPlain}
       selected={selected}
       {...getOUIAProps(
@@ -111,18 +152,15 @@ const SelectBase: React.FunctionComponent<SelectProps & OUIAProps> = ({
     </Menu>
   );
   return (
-    <div ref={containerRef}>
-      <Popper
-        trigger={toggle(toggleRef)}
-        triggerRef={toggleRef}
-        popper={menu}
-        popperRef={menuRef}
-        appendTo={containerRef.current || undefined}
-        isVisible={isOpen}
-        zIndex={zIndex}
-        {...popperProps}
-      />
-    </div>
+    <Popper
+      trigger={typeof toggle === 'function' ? toggle(toggleRef) : toggle.toggleNode}
+      triggerRef={toggleRef}
+      popper={menu}
+      popperRef={menuRef}
+      isVisible={isOpen}
+      zIndex={zIndex}
+      {...popperProps}
+    />
   );
 };
 

package/src/components/Select/SelectGroup.tsx

@@ -2,6 +2,9 @@ import React from 'react';
 import { css } from '@patternfly/react-styles';
 import { MenuGroupProps, MenuGroup } from '../Menu';
 
+/**
+ * See the MenuGroup section of the Menu documentation for additional props that may be passed.
+ */
 export interface SelectGroupProps extends Omit<MenuGroupProps, 'ref'> {
   /** Anything which can be rendered in a select group */
   children: React.ReactNode;

package/src/components/Select/SelectOption.tsx

@@ -2,11 +2,17 @@ import React from 'react';
 import { css } from '@patternfly/react-styles';
 import { MenuItemProps, MenuItem } from '../Menu';
 
+/**
+ * See the MenuItem section of the Menu documentation for additional props that may be passed.
+ */
+
 export interface SelectOptionProps extends Omit<MenuItemProps, 'ref'> {
   /** Anything which can be rendered in a select option */
   children?: React.ReactNode;
   /** Classes applied to root element of select option */
   className?: string;
+  /** @hide Forwarded ref */
+  innerRef?: React.Ref<HTMLAnchorElement | HTMLButtonElement>;
   /** Identifies the component in the Select onSelect callback */
   itemId?: any;
   /** Indicates the option has a checkbox */
@@ -17,15 +23,29 @@ export interface SelectOptionProps extends Omit<MenuItemProps, 'ref'> {
   isSelected?: boolean;
   /** Indicates the option is focused */
   isFocused?: boolean;
+  /** Render an external link icon on focus or hover, and set the link's
+   * "target" attribute to a value of "_blank".
+   */
+  isExternalLink?: boolean;
+  /** Render option with icon */
+  icon?: React.ReactNode;
+  /** Description of the option */
+  description?: React.ReactNode;
 }
 
-export const SelectOption: React.FunctionComponent<MenuItemProps> = ({
+const SelectOptionBase: React.FunctionComponent<MenuItemProps> = ({
   children,
   className,
+  innerRef,
   ...props
 }: SelectOptionProps) => (
-  <MenuItem className={css(className)} {...props}>
+  <MenuItem ref={innerRef} className={css(className)} {...props}>
     {children}
   </MenuItem>
 );
+
+export const SelectOption = React.forwardRef((props: SelectOptionProps, ref: React.Ref<any>) => (
+  <SelectOptionBase {...props} innerRef={ref} />
+));
+
 SelectOption.displayName = 'SelectOption';

package/src/components/Select/examples/Select.md

@@ -3,35 +3,82 @@ id: Select
 section: components
 subsection: menus
 cssPrefix: pf-c-select
-propComponents: ['Select', 'SelectOption', 'SelectGroup', 'SelectList', 'MenuToggle']
+propComponents:
+  ['Select', 'SelectOption', 'SelectGroup', 'SelectList', 'MenuToggle', 'SelectToggleProps', 'SelectPopperProps']
 ouia: true
 ---
 
 import TimesIcon from '@patternfly/react-icons/dist/esm/icons/times-icon';
+import BellIcon from '@patternfly/react-icons/dist/esm/icons/bell-icon';
 
 ## Examples
 
+`Select` builds off of the Menu component suite to wrap commonly used properties and functions for a select menu. See the [Menu documentation](/components/menus/menu) for a full list of properties that may be passed through `Select` to further customize the select menu, or the [custom menu examples](/components/menus/custom-menus) for additional examples of fully functional menus.
+
 ### Single
 
 ```ts file="./SelectBasic.tsx"
+
+```
+
+### Option variations
+
+Showcases different option variants and customizations that are commonly used in a select menu. For a more complete list, see the [Menu documentation](/components/menus/menu).
+
+```ts file="./SelectOptionVariations.tsx"
+
 ```
 
 ### Grouped single
 
 ```ts file="./SelectGrouped.tsx"
+
 ```
 
 ### Checkbox
 
 ```ts file="./SelectCheckbox.tsx"
+
 ```
 
 ### Typeahead
 
 ```ts file="./SelectTypeahead.tsx"
+
+```
+
+### Typeahead with create option
+
+```ts file="./SelectTypeaheadCreatable.tsx"
+
 ```
 
-### Multiple Typeahead
+### Multiple typeahead with chips
 
 ```ts file="./SelectMultiTypeahead.tsx"
+
+```
+
+### Multiple typeahead with create option
+
+```ts file="./SelectMultiTypeaheadCreatable.tsx"
+
+```
+
+### Multiple typeahead with checkboxes
+
+```ts file="./SelectMultiTypeaheadCheckbox.tsx"
+
+```
+
+### View more
+
+```ts file="./SelectViewMore.tsx"
+
+```
+
+### Footer
+
+```ts file="./SelectFooter.tsx"
+
 ```

package/src/components/Select/examples/SelectBasic.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
-import { Select, SelectOption, SelectList, MenuToggle, MenuToggleElement } from '@patternfly/react-core';
+import { Select, SelectOption, SelectList, MenuToggle, MenuToggleElement, Checkbox } from '@patternfly/react-core';
 
 export const SelectBasic: React.FunctionComponent = () => {
   const [isOpen, setIsOpen] = React.useState(false);
   const [selected, setSelected] = React.useState<string>('Select a value');
-  const menuRef = React.useRef<HTMLDivElement>(null);
+  const [isDisabled, setIsDisabled] = React.useState<boolean>(false);
 
   const onToggleClick = () => {
     setIsOpen(!isOpen);
@@ -23,6 +23,7 @@ export const SelectBasic: React.FunctionComponent = () => {
       ref={toggleRef}
       onClick={onToggleClick}
       isExpanded={isOpen}
+      isDisabled={isDisabled}
       style={
         {
           width: '200px'
@@ -34,20 +35,29 @@ export const SelectBasic: React.FunctionComponent = () => {
   );
 
   return (
-    <Select
-      id="single-select"
-      ref={menuRef}
-      isOpen={isOpen}
-      selected={selected}
-      onSelect={onSelect}
-      onOpenChange={isOpen => setIsOpen(isOpen)}
-      toggle={toggle}
-    >
-      <SelectList>
-        <SelectOption itemId="Option 1">Option 1</SelectOption>
-        <SelectOption itemId="Option 2">Option 2</SelectOption>
-        <SelectOption itemId="Option 3">Option 3</SelectOption>
-      </SelectList>
-    </Select>
+    <React.Fragment>
+      <Checkbox
+        id="toggle-disabled"
+        label="isDisabled"
+        isChecked={isDisabled}
+        onChange={(_event, checked) => setIsDisabled(checked)}
+        style={{ marginBottom: 20 }}
+      />
+      <Select
+        id="single-select"
+        isOpen={isOpen}
+        selected={selected}
+        onSelect={onSelect}
+        onOpenChange={(isOpen) => setIsOpen(isOpen)}
+        toggle={toggle}
+        shouldFocusToggleOnSelect
+      >
+        <SelectList>
+          <SelectOption itemId="Option 1">Option 1</SelectOption>
+          <SelectOption itemId="Option 2">Option 2</SelectOption>
+          <SelectOption itemId="Option 3">Option 3</SelectOption>
+        </SelectList>
+      </Select>
+    </React.Fragment>
   );
 };

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

@@ -4,7 +4,6 @@ import { Select, SelectOption, SelectList, MenuToggle, MenuToggleElement, Badge
 export const SelectCheckbox: React.FunctionComponent = () => {
   const [isOpen, setIsOpen] = React.useState(false);
   const [selectedItems, setSelectedItems] = React.useState<number[]>([]);
-  const menuRef = React.useRef<HTMLDivElement>(null);
 
   const onToggleClick = () => {
     setIsOpen(!isOpen);
@@ -15,7 +14,7 @@ export const SelectCheckbox: React.FunctionComponent = () => {
     console.log('selected', itemId);
 
     if (selectedItems.includes(itemId as number)) {
-      setSelectedItems(selectedItems.filter(id => id !== itemId));
+      setSelectedItems(selectedItems.filter((id) => id !== itemId));
     } else {
       setSelectedItems([...selectedItems, itemId as number]);
     }
@@ -41,7 +40,6 @@ export const SelectCheckbox: React.FunctionComponent = () => {
     <Select
       role="menu"
       id="checkbox-select"
-      ref={menuRef}
       isOpen={isOpen}
       selected={selectedItems}
       onSelect={onSelect}

package/src/components/Select/examples/SelectFooter.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import { MenuToggle, MenuFooter, Select, SelectList, SelectOption, Button } from '@patternfly/react-core';
+
+export const SelectFooter: React.FunctionComponent = () => {
+  const [isOpen, setIsOpen] = React.useState<boolean>(false);
+  const [selected, setSelected] = React.useState<string>('Select a value');
+
+  const onToggleClick = () => {
+    setIsOpen(!isOpen);
+  };
+
+  const toggle = (toggleRef) => (
+    <MenuToggle
+      ref={toggleRef}
+      onClick={onToggleClick}
+      isExpanded={isOpen}
+      style={
+        {
+          width: '200px'
+        } as React.CSSProperties
+      }
+    >
+      {selected}
+    </MenuToggle>
+  );
+
+  function onSelect(event: React.MouseEvent | undefined, itemId: string | number | undefined) {
+    if (typeof itemId === 'undefined') {
+      return;
+    }
+
+    setSelected(itemId.toString());
+  }
+
+  return (
+    <Select
+      isOpen={isOpen}
+      onOpenChange={(isOpen) => setIsOpen(isOpen)}
+      onOpenChangeKeys={['Escape']}
+      toggle={toggle}
+      id="menu-with-footer"
+      onSelect={onSelect}
+      selected={selected}
+    >
+      <SelectList>
+        <SelectOption itemId="Option 1">Option 1</SelectOption>
+        <SelectOption itemId="Option 2">Option 2</SelectOption>
+        <SelectOption itemId="Option 3">Option 3</SelectOption>
+      </SelectList>
+      <MenuFooter>
+        <Button variant="link" isInline>
+          Footer action
+        </Button>
+      </MenuFooter>
+    </Select>
+  );
+};

package/src/components/Select/examples/SelectGrouped.tsx

@@ -1,10 +1,17 @@
 import React from 'react';
-import { Select, SelectOption, SelectList, SelectGroup, MenuToggle, MenuToggleElement } from '@patternfly/react-core';
+import {
+  Select,
+  SelectOption,
+  SelectList,
+  SelectGroup,
+  MenuToggle,
+  MenuToggleElement,
+  Divider
+} from '@patternfly/react-core';
 
-export const SelectBasic: React.FunctionComponent = () => {
+export const SelectGrouped: React.FunctionComponent = () => {
   const [isOpen, setIsOpen] = React.useState(false);
   const [selected, setSelected] = React.useState<string>('Select a value');
-  const menuRef = React.useRef<HTMLDivElement>(null);
 
   const onToggleClick = () => {
     setIsOpen(!isOpen);
@@ -35,13 +42,13 @@ export const SelectBasic: React.FunctionComponent = () => {
 
   return (
     <Select
-      id="single-select"
-      ref={menuRef}
+      id="single-grouped-select"
       isOpen={isOpen}
       selected={selected}
       onSelect={onSelect}
-      onOpenChange={isOpen => setIsOpen(isOpen)}
+      onOpenChange={(isOpen) => setIsOpen(isOpen)}
       toggle={toggle}
+      shouldFocusToggleOnSelect
     >
       <SelectGroup label="Group 1">
         <SelectList>
@@ -50,6 +57,7 @@ export const SelectBasic: React.FunctionComponent = () => {
           <SelectOption itemId="Option 3">Option 3</SelectOption>
         </SelectList>
       </SelectGroup>
+      <Divider />
       <SelectGroup label="Group 2">
         <SelectList>
           <SelectOption itemId="Option 4">Option 4</SelectOption>

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

@@ -31,8 +31,6 @@ export const SelectMultiTypeahead: React.FunctionComponent = () => {
   const [selectOptions, setSelectOptions] = React.useState<SelectOptionProps[]>(initialSelectOptions);
   const [focusedItemIndex, setFocusedItemIndex] = React.useState<number | null>(null);
   const [activeItem, setActiveItem] = React.useState<string | null>(null);
-
-  const menuRef = React.useRef<HTMLDivElement>(null);
   const textInputRef = React.useRef<HTMLInputElement>();
 
   React.useEffect(() => {
@@ -40,10 +38,8 @@ export const SelectMultiTypeahead: React.FunctionComponent = () => {
 
     // Filter menu items based on the text input value when one exists
     if (inputValue) {
-      newSelectOptions = initialSelectOptions.filter(menuItem =>
-        String(menuItem.children)
-          .toLowerCase()
-          .includes(inputValue.toLowerCase())
+      newSelectOptions = initialSelectOptions.filter((menuItem) =>
+        String(menuItem.children).toLowerCase().includes(inputValue.toLowerCase())
       );
 
       // When no options are found after filtering, display 'No results found'
@@ -87,13 +83,13 @@ export const SelectMultiTypeahead: React.FunctionComponent = () => {
       }
 
       setFocusedItemIndex(indexToFocus);
-      const focusedItem = selectOptions.filter(option => !option.isDisabled)[indexToFocus];
+      const focusedItem = selectOptions.filter((option) => !option.isDisabled)[indexToFocus];
       setActiveItem(`select-multi-typeahead-${focusedItem.itemId.replace(' ', '-')}`);
     }
   };
 
   const onInputKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
-    const enabledMenuItems = selectOptions.filter(menuItem => !menuItem.isDisabled);
+    const enabledMenuItems = selectOptions.filter((menuItem) => !menuItem.isDisabled);
     const [firstMenuItem] = enabledMenuItems;
     const focusedItem = focusedItemIndex ? enabledMenuItems[focusedItemIndex] : firstMenuItem;
 
@@ -101,7 +97,7 @@ export const SelectMultiTypeahead: React.FunctionComponent = () => {
       // Select the first available option
       case 'Enter':
         if (!isOpen) {
-          setIsOpen(prevIsOpen => !prevIsOpen);
+          setIsOpen((prevIsOpen) => !prevIsOpen);
         } else if (isOpen && focusedItem.itemId !== 'no results') {
           onSelect(focusedItem.itemId as string);
         }
@@ -133,7 +129,7 @@ export const SelectMultiTypeahead: React.FunctionComponent = () => {
 
     if (itemId && itemId !== 'no results') {
       setSelected(
-        selected.includes(itemId) ? selected.filter(selection => selection !== itemId) : [...selected, itemId]
+        selected.includes(itemId) ? selected.filter((selection) => selection !== itemId) : [...selected, itemId]
       );
     }
 
@@ -161,7 +157,7 @@ export const SelectMultiTypeahead: React.FunctionComponent = () => {
             {selected.map((selection, index) => (
               <Chip
                 key={index}
-                onClick={ev => {
+                onClick={(ev) => {
                   ev.stopPropagation();
                   onSelect(selection);
                 }}
@@ -193,7 +189,6 @@ export const SelectMultiTypeahead: React.FunctionComponent = () => {
   return (
     <Select
       id="multi-typeahead-select"
-      ref={menuRef}
       isOpen={isOpen}
       selected={selected}
       onSelect={(ev, selection) => onSelect(selection as string)}