@react-stately/combobox 3.0.0-beta.1 → 3.0.0-nightly-4980928d3-240906

package/src/useComboBoxState.ts

@@ -10,29 +10,36 @@
  * governing permissions and limitations under the License.
  */
 
-import {Collection, FocusStrategy, Node} from '@react-types/shared';
+import {Collection, CollectionStateBase, FocusStrategy, Node} from '@react-types/shared';
 import {ComboBoxProps, MenuTriggerAction} from '@react-types/combobox';
+import {FormValidationState, useFormValidationState} from '@react-stately/form';
+import {getChildNodes} from '@react-stately/collections';
 import {ListCollection, useSingleSelectListState} from '@react-stately/list';
 import {SelectState} from '@react-stately/select';
+import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
 import {useControlledState} from '@react-stately/utils';
-import {useEffect, useMemo, useRef, useState} from 'react';
-import {useMenuTriggerState} from '@react-stately/menu';
+import {useOverlayTriggerState} from '@react-stately/overlays';
 
-export interface ComboBoxState<T> extends SelectState<T> {
+export interface ComboBoxState<T> extends SelectState<T>, FormValidationState{
   /** The current value of the combo box input. */
   inputValue: string,
   /** Sets the value of the combo box input. */
   setInputValue(value: string): void,
   /** Selects the currently focused item and updates the input value. */
   commit(): void,
+  /** Controls which item will be auto focused when the menu opens. */
+  readonly focusStrategy: FocusStrategy | null,
   /** Opens the menu. */
   open(focusStrategy?: FocusStrategy | null, trigger?: MenuTriggerAction): void,
   /** Toggles the menu. */
-  toggle(focusStrategy?: FocusStrategy | null, trigger?: MenuTriggerAction): void
+  toggle(focusStrategy?: FocusStrategy | null, trigger?: MenuTriggerAction): void,
+  /** Resets the input value to the previously selected item's text if any and closes the menu.  */
+  revert(): void
 }
 
 type FilterFn = (textValue: string, inputValue: string) => boolean;
-interface ComboBoxStateProps<T> extends ComboBoxProps<T> {
+
+export interface ComboBoxStateOptions<T> extends Omit<ComboBoxProps<T>, 'children'>, CollectionStateBase<T> {
   /** The filter function used to determine if a option should be included in the combo box list. */
   defaultFilter?: FilterFn,
   /** Whether the combo box allows the menu to be open when the collection is empty. */
@@ -46,7 +53,7 @@ interface ComboBoxStateProps<T> extends ComboBoxProps<T> {
  * of items from props and manages the option selection state of the combo box. In addition, it tracks the input value,
  * focus state, and other properties of the combo box.
  */
-export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>): ComboBoxState<T> {
+export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T>): ComboBoxState<T> {
   let {
     defaultFilter,
     menuTrigger = 'input',
@@ -57,32 +64,46 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>)
 
   let [showAllItems, setShowAllItems] = useState(false);
   let [isFocused, setFocusedState] = useState(false);
-  let [inputValue, setInputValue] = useControlledState(
-    props.inputValue,
-    props.defaultInputValue ?? '',
-    props.onInputChange
-  );
+  let [focusStrategy, setFocusStrategy] = useState<FocusStrategy | null>(null);
 
   let onSelectionChange = (key) => {
     if (props.onSelectionChange) {
       props.onSelectionChange(key);
     }
 
-    // If open state or selectedKey is uncontrolled and key is the same, reset the inputValue and close the menu
+    // If key is the same, reset the inputValue and close the menu
     // (scenario: user clicks on already selected option)
-    if (props.isOpen === undefined || props.selectedKey === undefined) {
-      if (key === selectedKey) {
-        resetInputValue();
-        triggerState.close();
-      }
+    if (key === selectedKey) {
+      resetInputValue();
+      closeMenu();
     }
   };
 
-  let {collection, selectionManager, selectedKey, setSelectedKey, selectedItem, disabledKeys} = useSingleSelectListState({
+  let {collection,
+    selectionManager,
+    selectedKey,
+    setSelectedKey,
+    selectedItem,
+    disabledKeys
+  } = useSingleSelectListState({
     ...props,
     onSelectionChange,
     items: props.items ?? props.defaultItems
   });
+  let defaultInputValue: string | null | undefined = props.defaultInputValue;
+  if (defaultInputValue == null) {
+    if (selectedKey == null) {
+      defaultInputValue = '';
+    } else {
+      defaultInputValue = collection.getItem(selectedKey)?.textValue ?? '';
+    }
+  }
+
+  let [inputValue, setInputValue] = useControlledState(
+    props.inputValue,
+    defaultInputValue!,
+    props.onInputChange
+  );
 
   // Preserve original collection so we can show all items on demand
   let originalCollection = collection;
@@ -92,17 +113,23 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>)
       ? collection
       : filterCollection(collection, inputValue, defaultFilter)
   ), [collection, inputValue, defaultFilter, props.items]);
+  let [lastCollection, setLastCollection] = useState(filteredCollection);
 
   // Track what action is attempting to open the menu
-  let menuOpenTrigger = useRef('focus' as MenuTriggerAction);
+  let menuOpenTrigger = useRef<MenuTriggerAction | undefined>('focus');
   let onOpenChange = (open: boolean) => {
     if (props.onOpenChange) {
       props.onOpenChange(open, open ? menuOpenTrigger.current : undefined);
     }
+
+    selectionManager.setFocused(open);
+    if (!open) {
+      selectionManager.setFocusedKey(null);
+    }
   };
 
-  let triggerState = useMenuTriggerState({...props, onOpenChange});
-  let open = (focusStrategy?: FocusStrategy, trigger?: MenuTriggerAction) => {
+  let triggerState = useOverlayTriggerState({...props, onOpenChange, isOpen: undefined, defaultOpen: undefined});
+  let open = (focusStrategy: FocusStrategy | null = null, trigger?: MenuTriggerAction) => {
     let displayAllItems = (trigger === 'manual' || (trigger === 'focus' && menuTrigger === 'focus'));
     // Prevent open operations from triggering if there is nothing to display
     // Also prevent open operations from triggering if items are uncontrolled but defaultItems is empty, even if displayAllItems is true.
@@ -114,11 +141,12 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>)
       }
 
       menuOpenTrigger.current = trigger;
-      triggerState.open(focusStrategy);
+      setFocusStrategy(focusStrategy);
+      triggerState.open();
     }
   };
 
-  let toggle = (focusStrategy?: FocusStrategy, trigger?: MenuTriggerAction) => {
+  let toggle = (focusStrategy: FocusStrategy | null = null, trigger?: MenuTriggerAction) => {
     let displayAllItems = (trigger === 'manual' || (trigger === 'focus' && menuTrigger === 'focus'));
     // If the menu is closed and there is nothing to display, early return so toggle isn't called to prevent extraneous onOpenChange
     if (!(allowsEmptyCollection || filteredCollection.size > 0 || (displayAllItems && originalCollection.size > 0) || props.items) && !triggerState.isOpen) {
@@ -135,58 +163,78 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>)
       menuOpenTrigger.current = trigger;
     }
 
-    triggerState.toggle(focusStrategy);
+    toggleMenu(focusStrategy);
   };
 
-  let lastValue = useRef(inputValue);
+  let updateLastCollection = useCallback(() => {
+    setLastCollection(showAllItems ? originalCollection : filteredCollection);
+  }, [showAllItems, originalCollection, filteredCollection]);
+
+  // If menu is going to close, save the current collection so we can freeze the displayed collection when the
+  // user clicks outside the popover to close the menu. Prevents the menu contents from updating as the menu closes.
+  let toggleMenu = useCallback((focusStrategy: FocusStrategy | null = null) => {
+    if (triggerState.isOpen) {
+      updateLastCollection();
+    }
+
+    setFocusStrategy(focusStrategy);
+    triggerState.toggle();
+  }, [triggerState, updateLastCollection]);
+
+  let closeMenu = useCallback(() => {
+    if (triggerState.isOpen) {
+      updateLastCollection();
+      triggerState.close();
+    }
+  }, [triggerState, updateLastCollection]);
+
+  let [lastValue, setLastValue] = useState(inputValue);
   let resetInputValue = () => {
-    let itemText = collection.getItem(selectedKey)?.textValue ?? '';
-    lastValue.current = itemText;
+    let itemText = selectedKey != null ? collection.getItem(selectedKey)?.textValue ?? '' : '';
+    setLastValue(itemText);
     setInputValue(itemText);
   };
 
-  let isInitialRender = useRef(true);
   let lastSelectedKey = useRef(props.selectedKey ?? props.defaultSelectedKey ?? null);
-  let lastSelectedKeyText = useRef(collection.getItem(selectedKey)?.textValue ?? '');
+  let lastSelectedKeyText = useRef(
+    selectedKey != null ? collection.getItem(selectedKey)?.textValue ?? '' : ''
+  );
   // intentional omit dependency array, want this to happen on every render
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(() => {
-    // If open state or inputValue is uncontrolled, open and close automatically when the input value changes,
-    // the input is if focused, and there are items in the collection or allowEmptyCollection is true.
+    // Open and close menu automatically when the input value changes if the input is focused,
+    // and there are items in the collection or allowEmptyCollection is true.
     if (
       isFocused &&
       (filteredCollection.size > 0 || allowsEmptyCollection) &&
       !triggerState.isOpen &&
-      inputValue !== lastValue.current &&
-      menuTrigger !== 'manual' &&
-      (props.isOpen === undefined || props.inputValue === undefined)
+      inputValue !== lastValue &&
+      menuTrigger !== 'manual'
     ) {
       open(null, 'input');
     }
 
-    // Close the menu if the collection is empty and either open state or items are uncontrolled.
-    // Don't close menu if filtered collection size is 0 but we are currently showing all items via button press (only applies to uncontrolled items)
+    // Close the menu if the collection is empty. Don't close menu if filtered collection size is 0
+    // but we are currently showing all items via button press
     if (
       !showAllItems &&
       !allowsEmptyCollection &&
       triggerState.isOpen &&
-      filteredCollection.size === 0 &&
-      (props.isOpen === undefined || props.items === undefined)
+      filteredCollection.size === 0
     ) {
-      triggerState.close();
+      closeMenu();
     }
 
-    // Close when an item is selected, if open state or selectedKey is uncontrolled.
+    // Close when an item is selected.
     if (
       selectedKey != null &&
-      selectedKey !== lastSelectedKey.current &&
-      (props.isOpen === undefined || props.selectedKey === undefined)
+      selectedKey !== lastSelectedKey.current
     ) {
-      triggerState.close();
+      closeMenu();
     }
 
     // Clear focused key when input value changes and display filtered collection again.
-    if (inputValue !== lastValue.current) {
+    if (inputValue !== lastValue) {
       selectionManager.setFocusedKey(null);
       setShowAllItems(false);
 
@@ -197,11 +245,6 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>)
       }
     }
 
-    // If it is the intial render and inputValue isn't controlled nor has an intial value, set input to match current selected key if any
-    if (isInitialRender.current && (props.inputValue === undefined && props.defaultInputValue === undefined)) {
-      resetInputValue();
-    }
-
     // If the selectedKey changed, update the input value.
     // Do nothing if both inputValue and selectedKey are controlled.
     // In this case, it's the user's responsibility to update inputValue in onSelectionChange.
@@ -210,81 +253,69 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>)
       (props.inputValue === undefined || props.selectedKey === undefined)
     ) {
       resetInputValue();
-    } else {
-      lastValue.current = inputValue;
+    } else if (lastValue !== inputValue) {
+      setLastValue(inputValue);
     }
 
     // Update the inputValue if the selected item's text changes from its last tracked value.
     // This is to handle cases where a selectedKey is specified but the items aren't available (async loading) or the selected item's text value updates.
     // Only reset if the user isn't currently within the field so we don't erroneously modify user input.
     // If inputValue is controlled, it is the user's responsibility to update the inputValue when items change.
-    let selectedItemText = collection.getItem(selectedKey)?.textValue ?? '';
+    let selectedItemText = selectedKey != null ? collection.getItem(selectedKey)?.textValue ?? '' : '';
     if (!isFocused && selectedKey != null && props.inputValue === undefined && selectedKey === lastSelectedKey.current) {
       if (lastSelectedKeyText.current !== selectedItemText) {
-        lastValue.current = selectedItemText;
+        setLastValue(selectedItemText);
         setInputValue(selectedItemText);
       }
     }
 
-    isInitialRender.current = false;
     lastSelectedKey.current = selectedKey;
     lastSelectedKeyText.current = selectedItemText;
   });
 
-  useEffect(() => {
-    // Reset focused key when the menu closes
-    if (!triggerState.isOpen) {
-      selectionManager.setFocusedKey(null);
+  let validation = useFormValidationState({
+    ...props,
+    value: useMemo(() => ({inputValue, selectedKey}), [inputValue, selectedKey])
+  });
+
+  // Revert input value and close menu
+  let revert = () => {
+    if (allowsCustomValue && selectedKey == null) {
+      commitCustomValue();
+    } else {
+      commitSelection();
     }
-  }, [triggerState.isOpen, selectionManager]);
+  };
 
   let commitCustomValue = () => {
-    let shouldClose = false;
     lastSelectedKey.current = null;
     setSelectedKey(null);
-
-    // If previous key was already null, need to manually call onSelectionChange since it won't be triggered by a setSelectedKey call
-    // This allows the application to control whether or not to close the menu on custom value commit
-    if (selectedKey === null && props.onSelectionChange) {
-      props.onSelectionChange(null);
-    }
-
-    // Should close menu ourselves if component open state or selected key is uncontrolled and therefore won't be closed by a user defined event handler
-    shouldClose = props.isOpen == null || props.selectedKey === undefined;
-
-    // Close if no other event will be fired. Otherwise, allow the
-    // application to control this based on that event.
-    if (shouldClose) {
-      triggerState.close();
-    }
+    closeMenu();
   };
 
   let commitSelection = () => {
     // If multiple things are controlled, call onSelectionChange
-    // Note that users who control open state and input value MUST also have a onSelectionChange handler to properly close the menu and reset input value
-    if (
-      (props.selectedKey !== undefined && props.inputValue !== undefined) ||
-      (props.inputValue !== undefined && props.isOpen !== undefined) ||
-      (props.selectedKey !== undefined && props.isOpen !== undefined)
-    ) {
-      props.onSelectionChange(selectedKey);
-
-      // If multiple things are controlled but inputValue isn't, reset the input value for the user
-      if (props.inputValue === undefined) {
-        resetInputValue();
-      }
+    if (props.selectedKey !== undefined && props.inputValue !== undefined) {
+      props.onSelectionChange?.(selectedKey);
 
-      // If multiple things are controlled but isOpen isn't, close the menu for the user
-      if (props.isOpen === undefined) {
-        // Stop menu from reopening from useEffect
-        let itemText = collection.getItem(selectedKey)?.textValue ?? '';
-        lastValue.current = itemText;
-        triggerState.close();
-      }
+      // Stop menu from reopening from useEffect
+      let itemText = selectedKey != null ? collection.getItem(selectedKey)?.textValue ?? '' : '';
+      setLastValue(itemText);
+      closeMenu();
     } else {
       // If only a single aspect of combobox is controlled, reset input value and close menu for the user
       resetInputValue();
-      triggerState.close();
+      closeMenu();
+    }
+  };
+
+  const commitValue = () => {
+    if (allowsCustomValue) {
+      const itemText = selectedKey != null ? collection.getItem(selectedKey)?.textValue ?? '' : '';
+      (inputValue === itemText) ? commitSelection() : commitCustomValue();
+    } else {
+      // Reset inputValue and close menu
+      commitSelection();
     }
   };
 
@@ -297,32 +328,50 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>)
       } else {
         setSelectedKey(selectionManager.focusedKey);
       }
-    } else if (allowsCustomValue) {
-      commitCustomValue();
+    } else {
+      commitValue();
     }
   };
 
+  let valueOnFocus = useRef(inputValue);
   let setFocused = (isFocused: boolean) => {
     if (isFocused) {
-      if (menuTrigger === 'focus') {
+      valueOnFocus.current = inputValue;
+      if (menuTrigger === 'focus' && !props.isReadOnly) {
         open(null, 'focus');
       }
-    } else if (shouldCloseOnBlur) {
-      let itemText = collection.getItem(selectedKey)?.textValue ?? '';
-      if (allowsCustomValue && inputValue !== itemText) {
-        commitCustomValue();
-      } else {
-        commitSelection();
+    } else {
+      if (shouldCloseOnBlur) {
+        commitValue();
+      }
+
+      if (inputValue !== valueOnFocus.current) {
+        validation.commitValidation();
       }
     }
 
     setFocusedState(isFocused);
   };
 
+  let displayedCollection = useMemo(() => {
+    if (triggerState.isOpen) {
+      if (showAllItems) {
+        return originalCollection;
+      } else {
+        return filteredCollection;
+      }
+    } else {
+      return lastCollection;
+    }
+  }, [triggerState.isOpen, originalCollection, filteredCollection, showAllItems, lastCollection]);
+
   return {
+    ...validation,
     ...triggerState,
+    focusStrategy,
     toggle,
     open,
+    close: commitValue,
     selectionManager,
     selectedKey,
     setSelectedKey,
@@ -330,26 +379,29 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>)
     isFocused,
     setFocused,
     selectedItem,
-    collection: showAllItems ? originalCollection : filteredCollection,
+    collection: displayedCollection,
     inputValue,
     setInputValue,
-    commit
+    commit,
+    revert
   };
 }
 
 function filterCollection<T extends object>(collection: Collection<Node<T>>, inputValue: string, filter: FilterFn): Collection<Node<T>> {
-  return new ListCollection(filterNodes(collection, inputValue, filter));
+  return new ListCollection(filterNodes(collection, collection, inputValue, filter));
 }
 
-function filterNodes<T>(nodes: Iterable<Node<T>>, inputValue: string, filter: FilterFn): Iterable<Node<T>> {
-  let filteredNode = [];
+function filterNodes<T>(collection: Collection<Node<T>>, nodes: Iterable<Node<T>>, inputValue: string, filter: FilterFn): Iterable<Node<T>> {
+  let filteredNode: Node<T>[] = [];
   for (let node of nodes) {
     if (node.type === 'section' && node.hasChildNodes) {
-      let filtered = filterNodes(node.childNodes, inputValue, filter);
-      if ([...filtered].length > 0) {
+      let filtered = filterNodes(collection, getChildNodes(node, collection), inputValue, filter);
+      if ([...filtered].some(node => node.type === 'item')) {
         filteredNode.push({...node, childNodes: filtered});
       }
-    } else if (node.type !== 'section' && filter(node.textValue, inputValue)) {
+    } else if (node.type === 'item' && filter(node.textValue, inputValue)) {
+      filteredNode.push({...node});
+    } else if (node.type !== 'item') {
       filteredNode.push({...node});
     }
   }