@react-stately/combobox 3.0.0-beta.0 → 3.0.0-nightly-641446f65-240905

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@react-stately/combobox",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0-nightly-641446f65-240905",
   "description": "Spectrum UI components in React",
   "license": "Apache-2.0",
   "main": "dist/main.js",
   "module": "dist/module.js",
+  "exports": {
+    "types": "./dist/types.d.ts",
+    "import": "./dist/import.mjs",
+    "require": "./dist/main.js"
+  },
   "types": "dist/types.d.ts",
   "source": "src/index.ts",
   "files": [
@@ -17,19 +22,21 @@
     "url": "https://github.com/adobe/react-spectrum"
   },
   "dependencies": {
-    "@babel/runtime": "^7.6.2",
-    "@react-stately/list": "^3.2.2",
-    "@react-stately/menu": "^3.1.0",
-    "@react-stately/select": "^3.1.0",
-    "@react-stately/utils": "^3.2.0",
-    "@react-types/combobox": "3.0.0-beta.0",
-    "@react-types/shared": "^3.5.0"
+    "@react-stately/collections": "^3.0.0-nightly-641446f65-240905",
+    "@react-stately/form": "^3.0.0-nightly-641446f65-240905",
+    "@react-stately/list": "^3.0.0-nightly-641446f65-240905",
+    "@react-stately/overlays": "^3.0.0-nightly-641446f65-240905",
+    "@react-stately/select": "^3.0.0-nightly-641446f65-240905",
+    "@react-stately/utils": "^3.0.0-nightly-641446f65-240905",
+    "@react-types/combobox": "^3.0.0-nightly-641446f65-240905",
+    "@react-types/shared": "^3.0.0-nightly-641446f65-240905",
+    "@swc/helpers": "^0.5.0"
   },
   "peerDependencies": {
-    "react": "^16.8.0 || ^17.0.0-rc.1"
+    "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9920ffaa2596a03c4498a15cb940bd2f4ba5cd6a"
-}
+  "stableVersion": "3.9.2"
+}

package/src/index.ts

@@ -10,4 +10,6 @@
  * governing permissions and limitations under the License.
  */
 
-export * from './useComboBoxState';
+export {useComboBoxState} from './useComboBoxState';
+
+export type {ComboBoxStateOptions, ComboBoxState} from './useComboBoxState';

package/src/useComboBoxState.ts

@@ -10,25 +10,36 @@
  * governing permissions and limitations under the License.
  */
 
-import {Collection, FocusStrategy, Node} from '@react-types/shared';
-import {ComboBoxProps} from '@react-types/combobox';
+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
+  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,
+  /** 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. */
@@ -42,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',
@@ -51,103 +62,181 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>)
     shouldCloseOnBlur = true
   } = props;
 
+  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;
   let filteredCollection = useMemo(() => (
     // No default filter if items are controlled.
     props.items != null || !defaultFilter
       ? 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<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);
-  let open = (focusStrategy?: FocusStrategy) => {
+  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
-    if (allowsEmptyCollection || filteredCollection.size > 0) {
-      triggerState.open(focusStrategy);
+    // Also prevent open operations from triggering if items are uncontrolled but defaultItems is empty, even if displayAllItems is true.
+    // This is to prevent comboboxes with empty defaultItems from opening but allow controlled items comboboxes to open even if the inital list is empty (assumption is user will provide swap the empty list with a base list via onOpenChange returning `menuTrigger` manual)
+    if (allowsEmptyCollection || filteredCollection.size > 0 || (displayAllItems && originalCollection.size > 0) || props.items) {
+      if (displayAllItems && !triggerState.isOpen && props.items === undefined) {
+        // Show all items if menu is manually opened. Only care about this if items are undefined
+        setShowAllItems(true);
+      }
+
+      menuOpenTrigger.current = trigger;
+      setFocusStrategy(focusStrategy);
+      triggerState.open();
     }
   };
 
-  let toggle = (focusStrategy?: FocusStrategy) => {
+  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) && !triggerState.isOpen) {
+    if (!(allowsEmptyCollection || filteredCollection.size > 0 || (displayAllItems && originalCollection.size > 0) || props.items) && !triggerState.isOpen) {
       return;
     }
 
-    triggerState.toggle(focusStrategy);
+    if (displayAllItems && !triggerState.isOpen && props.items === undefined) {
+      // Show all items if menu is toggled open. Only care about this if items are undefined
+      setShowAllItems(true);
+    }
+
+    // Only update the menuOpenTrigger if menu is currently closed
+    if (!triggerState.isOpen) {
+      menuOpenTrigger.current = trigger;
+    }
+
+    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(
+    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();
+      open(null, 'input');
     }
 
-    // Close the menu if the collection is empty and either open state or items are uncontrolled.
+    // 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.
-    if (inputValue !== lastValue.current) {
+    // Clear focused key when input value changes and display filtered collection again.
+    if (inputValue !== lastValue) {
       selectionManager.setFocusedKey(null);
+      setShowAllItems(false);
 
       // Set selectedKey to null when the user clears the input.
       // If controlled, this is the application developer's responsibility.
@@ -156,82 +245,77 @@ 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. In addition, we preserve the defaultInputValue
-    // on initial render, even if it doesn't match the selected item's text.
+    // In this case, it's the user's responsibility to update inputValue in onSelectionChange.
     if (
       selectedKey !== lastSelectedKey.current &&
       (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 = selectedKey != null ? collection.getItem(selectedKey)?.textValue ?? '' : '';
+    if (!isFocused && selectedKey != null && props.inputValue === undefined && selectedKey === lastSelectedKey.current) {
+      if (lastSelectedKeyText.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();
     }
   };
 
@@ -244,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') {
-        open();
+      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,
@@ -277,27 +379,30 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateProps<T>)
     isFocused,
     setFocused,
     selectedItem,
-    collection: 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)) {
-      filteredNode.push(node);
+    } else if (node.type === 'item' && filter(node.textValue, inputValue)) {
+      filteredNode.push({...node});
+    } else if (node.type !== 'item') {
+      filteredNode.push({...node});
     }
   }
   return filteredNode;