@react-aria/autocomplete 3.0.0-alpha.9 → 3.0.0-beta.0

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@react-aria/autocomplete",
-  "version": "3.0.0-alpha.9",
+  "version": "3.0.0-beta.0",
   "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,30 +22,27 @@
     "url": "https://github.com/adobe/react-spectrum"
   },
   "dependencies": {
-    "@babel/runtime": "^7.6.2",
-    "@react-aria/combobox": "^3.4.0",
-    "@react-aria/i18n": "^3.5.0",
-    "@react-aria/listbox": "^3.6.0",
-    "@react-aria/live-announcer": "^3.1.1",
-    "@react-aria/menu": "^3.6.0",
-    "@react-aria/overlays": "^3.10.0",
-    "@react-aria/searchfield": "^3.4.0",
-    "@react-aria/selection": "^3.10.0",
-    "@react-aria/textfield": "^3.7.0",
-    "@react-aria/utils": "^3.13.2",
-    "@react-stately/collections": "^3.4.2",
-    "@react-stately/combobox": "^3.2.0",
-    "@react-types/autocomplete": "3.0.0-alpha.7",
-    "@react-types/button": "^3.6.0",
-    "@react-types/combobox": "^3.5.2",
-    "@react-types/searchfield": "^3.3.2",
-    "@react-types/shared": "^3.14.0"
+    "@react-aria/combobox": "^3.12.0",
+    "@react-aria/focus": "^3.20.0",
+    "@react-aria/i18n": "^3.12.6",
+    "@react-aria/interactions": "^3.24.0",
+    "@react-aria/listbox": "^3.14.1",
+    "@react-aria/searchfield": "^3.8.1",
+    "@react-aria/textfield": "^3.17.0",
+    "@react-aria/utils": "^3.28.0",
+    "@react-stately/autocomplete": "3.0.0-beta.0",
+    "@react-stately/combobox": "^3.10.3",
+    "@react-types/autocomplete": "3.0.0-alpha.29",
+    "@react-types/button": "^3.11.0",
+    "@react-types/shared": "^3.28.0",
+    "@swc/helpers": "^0.5.0"
   },
   "peerDependencies": {
-    "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0"
+    "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1",
+    "react-dom": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "cd7c0ec917122c7612f653c22f8ed558f8b66ecd"
+  "gitHead": "4d3c72c94eea2d72eb3a0e7d56000c6ef7e39726"
 }

package/src/index.ts

@@ -10,4 +10,8 @@
  * governing permissions and limitations under the License.
  */
 export {useSearchAutocomplete} from './useSearchAutocomplete';
-export type {AriaSearchAutocompleteProps, SearchAutocompleteAria} from './useSearchAutocomplete';
+export {useAutocomplete} from './useAutocomplete';
+
+export type {AriaSearchAutocompleteOptions, SearchAutocompleteAria} from './useSearchAutocomplete';
+export type {AriaSearchAutocompleteProps} from '@react-types/autocomplete';
+export type {AriaAutocompleteProps, AriaAutocompleteOptions, AutocompleteAria, CollectionOptions} from './useAutocomplete';

package/src/useAutocomplete.ts

@@ -0,0 +1,364 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {AriaLabelingProps, BaseEvent, DOMProps, RefObject} from '@react-types/shared';
+import {AriaTextFieldProps} from '@react-aria/textfield';
+import {AutocompleteProps, AutocompleteState} from '@react-stately/autocomplete';
+import {CLEAR_FOCUS_EVENT, FOCUS_EVENT, getActiveElement, getOwnerDocument, isCtrlKeyPressed, mergeProps, mergeRefs, useEffectEvent, useId, useLabels, useObjectRef} from '@react-aria/utils';
+import {dispatchVirtualBlur, dispatchVirtualFocus, moveVirtualFocus} from '@react-aria/focus';
+import {getInteractionModality} from '@react-aria/interactions';
+// @ts-ignore
+import intlMessages from '../intl/*.json';
+import {FocusEvent as ReactFocusEvent, KeyboardEvent as ReactKeyboardEvent, useCallback, useEffect, useMemo, useRef} from 'react';
+import {useLocalizedStringFormatter} from '@react-aria/i18n';
+
+export interface CollectionOptions extends DOMProps, AriaLabelingProps {
+  /** Whether the collection items should use virtual focus instead of being focused directly. */
+  shouldUseVirtualFocus: boolean,
+  /** Whether typeahead is disabled. */
+  disallowTypeAhead: boolean
+}
+export interface AriaAutocompleteProps extends AutocompleteProps {
+  /**
+   * An optional filter function used to determine if a option should be included in the autocomplete list.
+   * Include this if the items you are providing to your wrapped collection aren't filtered by default.
+   */
+  filter?: (textValue: string, inputValue: string) => boolean,
+
+  /**
+   * Whether or not to focus the first item in the collection after a filter is performed.
+   * @default false
+   */
+  disableAutoFocusFirst?: boolean
+}
+
+export interface AriaAutocompleteOptions extends Omit<AriaAutocompleteProps, 'children'> {
+  /** The ref for the wrapped collection element. */
+  inputRef: RefObject<HTMLInputElement | null>,
+  /** The ref for the wrapped collection element. */
+  collectionRef: RefObject<HTMLElement | null>
+}
+
+export interface AutocompleteAria {
+  /** Props for the autocomplete textfield/searchfield element. These should be passed to the textfield/searchfield aria hooks respectively. */
+  textFieldProps: AriaTextFieldProps,
+  /** Props for the collection, to be passed to collection's respective aria hook (e.g. useMenu). */
+  collectionProps: CollectionOptions,
+  /** Ref to attach to the wrapped collection. */
+  collectionRef: RefObject<HTMLElement | null>,
+  /** A filter function that returns if the provided collection node should be filtered out of the collection. */
+  filter?: (nodeTextValue: string) => boolean
+}
+
+/**
+ * Provides the behavior and accessibility implementation for an autocomplete component.
+ * An autocomplete combines a text input with a collection, allowing users to filter the collection's contents match a query.
+ * @param props - Props for the autocomplete.
+ * @param state - State for the autocomplete, as returned by `useAutocompleteState`.
+ */
+export function useAutocomplete(props: AriaAutocompleteOptions, state: AutocompleteState): AutocompleteAria {
+  let {
+    inputRef,
+    collectionRef,
+    filter,
+    disableAutoFocusFirst = false
+  } = props;
+
+  let collectionId = useId();
+  let timeout = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  let delayNextActiveDescendant = useRef(false);
+  let queuedActiveDescendant = useRef<string | null>(null);
+  let lastCollectionNode = useRef<HTMLElement>(null);
+
+  // For mobile screen readers, we don't want virtual focus, instead opting to disable FocusScope's restoreFocus and manually
+  // moving focus back to the subtriggers
+  let shouldUseVirtualFocus = getInteractionModality() !== 'virtual';
+
+  useEffect(() => {
+    return () => clearTimeout(timeout.current);
+  }, []);
+
+  let updateActiveDescendant = useEffectEvent((e: Event) => {
+    // Ensure input is focused if the user clicks on the collection directly.
+    if (!e.isTrusted && shouldUseVirtualFocus && inputRef.current && getActiveElement(getOwnerDocument(inputRef.current)) !== inputRef.current) {
+      inputRef.current.focus();
+    }
+
+    let target = e.target as Element | null;
+    if (e.isTrusted || !target || queuedActiveDescendant.current === target.id) {
+      return;
+    }
+
+    clearTimeout(timeout.current);
+    if (target !== collectionRef.current) {
+      if (delayNextActiveDescendant.current) {
+        queuedActiveDescendant.current = target.id;
+        timeout.current = setTimeout(() => {
+          state.setFocusedNodeId(target.id);
+        }, 500);
+      } else {
+        queuedActiveDescendant.current = target.id;
+        state.setFocusedNodeId(target.id);
+      }
+    } else {
+      queuedActiveDescendant.current = null;
+      state.setFocusedNodeId(null);
+    }
+
+    delayNextActiveDescendant.current = false;
+  });
+
+  let callbackRef = useCallback((collectionNode) => {
+    if (collectionNode != null) {
+      // When typing forward, we want to delay the setting of active descendant to not interrupt the native screen reader announcement
+      // of the letter you just typed. If we recieve another focus event then we clear the queued update
+      // We track lastCollectionNode to do proper cleanup since callbackRefs just pass null when unmounting. This also handles
+      // React 19's extra call of the callback ref in strict mode
+      lastCollectionNode.current?.removeEventListener('focusin', updateActiveDescendant);
+      lastCollectionNode.current = collectionNode;
+      collectionNode.addEventListener('focusin', updateActiveDescendant);
+    } else {
+      lastCollectionNode.current?.removeEventListener('focusin', updateActiveDescendant);
+    }
+  }, [updateActiveDescendant]);
+
+  // Make sure to memo so that React doesn't keep registering a new event listeners on every rerender of the wrapped collection
+  let mergedCollectionRef = useObjectRef(useMemo(() => mergeRefs(collectionRef, callbackRef), [collectionRef, callbackRef]));
+
+  let focusFirstItem = useEffectEvent(() => {
+    delayNextActiveDescendant.current = true;
+    collectionRef.current?.dispatchEvent(
+      new CustomEvent(FOCUS_EVENT, {
+        cancelable: true,
+        bubbles: true,
+        detail: {
+          focusStrategy: 'first'
+        }
+      })
+    );
+  });
+
+  let clearVirtualFocus = useEffectEvent((clearFocusKey?: boolean) => {
+    moveVirtualFocus(getActiveElement());
+    queuedActiveDescendant.current = null;
+    state.setFocusedNodeId(null);
+    let clearFocusEvent = new CustomEvent(CLEAR_FOCUS_EVENT, {
+      cancelable: true,
+      bubbles: true,
+      detail: {
+        clearFocusKey
+      }
+    });
+    clearTimeout(timeout.current);
+    delayNextActiveDescendant.current = false;
+    collectionRef.current?.dispatchEvent(clearFocusEvent);
+  });
+
+  // TODO: update to see if we can tell what kind of event (paste vs backspace vs typing) is happening instead
+  let onChange = (value: string) => {
+    // Tell wrapped collection to focus the first element in the list when typing forward and to clear focused key when deleting text
+    // for screen reader announcements
+    if (state.inputValue !== value && state.inputValue.length <= value.length && !disableAutoFocusFirst) {
+      focusFirstItem();
+    } else {
+      // Fully clear focused key when backspacing since the list may change and thus we'd want to start fresh again
+      clearVirtualFocus(true);
+    }
+
+    state.setInputValue(value);
+  };
+
+  let keyDownTarget = useRef<Element | null>(null);
+  // For textfield specific keydown operations
+  let onKeyDown = (e: BaseEvent<ReactKeyboardEvent<any>>) => {
+    keyDownTarget.current = e.target as Element;
+    if (e.nativeEvent.isComposing) {
+      return;
+    }
+
+    let focusedNodeId = queuedActiveDescendant.current;
+    switch (e.key) {
+      case 'a':
+        if (isCtrlKeyPressed(e)) {
+          return;
+        }
+        break;
+      case 'Escape':
+        // Early return for Escape here so it doesn't leak the Escape event from the simulated collection event below and
+        // close the dialog prematurely. Ideally that should be up to the discretion of the input element hence the check
+        // for isPropagationStopped
+        if (e.isDefaultPrevented()) {
+          return;
+        }
+        break;
+      case ' ':
+        // Space shouldn't trigger onAction so early return.
+        return;
+      case 'Tab':
+        // Don't propogate Tab down to the collection, otherwise we will try to focus the collection via useSelectableCollection's Tab handler (aka shift tab logic)
+        // We want FocusScope to handle Tab if one exists (aka sub dialog), so special casepropogate
+        if ('continuePropagation' in e) {
+          e.continuePropagation();
+        }
+        return;
+      case 'Home':
+      case 'End':
+      case 'PageDown':
+      case 'PageUp':
+      case 'ArrowUp':
+      case 'ArrowDown': {
+        if ((e.key === 'Home' || e.key === 'End') && focusedNodeId == null && e.shiftKey) {
+          return;
+        }
+
+        // Prevent these keys from moving the text cursor in the input
+        e.preventDefault();
+        // Move virtual focus into the wrapped collection
+        let focusCollection = new CustomEvent(FOCUS_EVENT, {
+          cancelable: true,
+          bubbles: true
+        });
+
+        collectionRef.current?.dispatchEvent(focusCollection);
+        break;
+      }
+    }
+
+    // Emulate the keyboard events that happen in the input field in the wrapped collection. This is for triggering things like onAction via Enter
+    // or moving focus from one item to another. Stop propagation on the input event if it isn't already stopped so it doesn't leak out. For events
+    // like ESC, the dispatched event below will bubble out of the collection and be stopped if handled by useSelectableCollection, otherwise will bubble
+    // as expected
+    if (!e.isPropagationStopped()) {
+      e.stopPropagation();
+    }
+
+    let shouldPerformDefaultAction = true;
+    if (focusedNodeId == null) {
+      shouldPerformDefaultAction = collectionRef.current?.dispatchEvent(
+        new KeyboardEvent(e.nativeEvent.type, e.nativeEvent)
+      ) || false;
+    } else {
+      let item = document.getElementById(focusedNodeId);
+      shouldPerformDefaultAction = item?.dispatchEvent(
+        new KeyboardEvent(e.nativeEvent.type, e.nativeEvent)
+      ) || false;
+    }
+
+    if (shouldPerformDefaultAction) {
+      switch (e.key) {
+        case 'ArrowLeft':
+        case 'ArrowRight': {
+          // Clear the activedescendant so NVDA announcements aren't interrupted but retain the focused key in the collection so the
+          // user's keyboard navigation restarts from where they left off
+          clearVirtualFocus();
+          break;
+        }
+      }
+    }
+  };
+
+  let onKeyUpCapture = useEffectEvent((e) => {
+    // Dispatch simulated key up events for things like triggering links in listbox
+    // Make sure to stop the propagation of the input keyup event so that the simulated keyup/down pair
+    // is detected by usePress instead of the original keyup originating from the input
+    if (e.target === keyDownTarget.current) {
+      e.stopImmediatePropagation();
+      let focusedNodeId = queuedActiveDescendant.current;
+      if (focusedNodeId == null) {
+        collectionRef.current?.dispatchEvent(
+          new KeyboardEvent(e.type, e)
+        );
+      } else {
+        let item = document.getElementById(focusedNodeId);
+        item?.dispatchEvent(
+          new KeyboardEvent(e.type, e)
+        );
+      }
+    }
+  });
+
+  useEffect(() => {
+    document.addEventListener('keyup', onKeyUpCapture, true);
+    return () => {
+      document.removeEventListener('keyup', onKeyUpCapture, true);
+    };
+  }, [onKeyUpCapture]);
+
+  let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-aria/autocomplete');
+  let collectionProps = useLabels({
+    id: collectionId,
+    'aria-label': stringFormatter.format('collectionLabel')
+  });
+
+  let filterFn = useCallback((nodeTextValue: string) => {
+    if (filter) {
+      return filter(nodeTextValue, state.inputValue);
+    }
+
+    return true;
+  }, [state.inputValue, filter]);
+
+  // Be sure to clear/restore the virtual + collection focus when blurring/refocusing the field so we only show the
+  // focus ring on the virtually focused collection when are actually interacting with the Autocomplete
+  let onBlur = (e: ReactFocusEvent) => {
+    if (!e.isTrusted) {
+      return;
+    }
+
+    let lastFocusedNode = queuedActiveDescendant.current ? document.getElementById(queuedActiveDescendant.current) : null;
+    if (lastFocusedNode) {
+      dispatchVirtualBlur(lastFocusedNode, e.relatedTarget);
+    }
+  };
+
+  let onFocus = (e: ReactFocusEvent) => {
+    if (!e.isTrusted) {
+      return;
+    }
+
+    let curFocusedNode = queuedActiveDescendant.current ? document.getElementById(queuedActiveDescendant.current) : null;
+    if (curFocusedNode) {
+      let target = e.target;
+      queueMicrotask(() => {
+        dispatchVirtualBlur(target, curFocusedNode);
+        dispatchVirtualFocus(curFocusedNode, target);
+      });
+    }
+  };
+
+  return {
+    textFieldProps: {
+      value: state.inputValue,
+      onChange,
+      onKeyDown,
+      autoComplete: 'off',
+      'aria-haspopup': 'listbox',
+      'aria-controls': collectionId,
+      // TODO: readd proper logic for completionMode = complete (aria-autocomplete: both)
+      'aria-autocomplete': 'list',
+      'aria-activedescendant': state.focusedNodeId ?? undefined,
+      // This disable's iOS's autocorrect suggestions, since the autocomplete provides its own suggestions.
+      autoCorrect: 'off',
+      // This disable's the macOS Safari spell check auto corrections.
+      spellCheck: 'false',
+      enterKeyHint: 'go',
+      onBlur,
+      onFocus
+    },
+    collectionProps: mergeProps(collectionProps, {
+      shouldUseVirtualFocus,
+      disallowTypeAhead: true
+    }),
+    collectionRef: mergedCollectionRef,
+    filter: filter != null ? filterFn : undefined
+  };
+}

package/src/useSearchAutocomplete.ts

@@ -12,27 +12,15 @@
 
 import {AriaButtonProps} from '@react-types/button';
 import {AriaListBoxOptions} from '@react-aria/listbox';
+import {AriaSearchAutocompleteProps} from '@react-types/autocomplete';
 import {ComboBoxState} from '@react-stately/combobox';
-import {DOMAttributes} from '@react-types/shared';
-import {InputHTMLAttributes, RefObject} from 'react';
-import {KeyboardDelegate} from '@react-types/shared';
+import {DOMAttributes, KeyboardDelegate, LayoutDelegate, RefObject, ValidationResult} from '@react-types/shared';
+import {InputHTMLAttributes} from 'react';
 import {mergeProps} from '@react-aria/utils';
-import {SearchAutocompleteProps} from '@react-types/autocomplete';
 import {useComboBox} from '@react-aria/combobox';
 import {useSearchField} from '@react-aria/searchfield';
 
-export interface AriaSearchAutocompleteProps<T> extends SearchAutocompleteProps<T> {
-  /** The ref for the input element. */
-  inputRef: RefObject<HTMLInputElement>,
-  /** The ref for the list box popover. */
-  popoverRef: RefObject<HTMLDivElement>,
-  /** The ref for the list box. */
-  listBoxRef: RefObject<HTMLElement>,
-  /** An optional keyboard delegate implementation, to override the default. */
-  keyboardDelegate?: KeyboardDelegate
-}
-
-export interface SearchAutocompleteAria<T> {
+export interface SearchAutocompleteAria<T> extends ValidationResult {
   /** Props for the label element. */
   labelProps: DOMAttributes,
   /** Props for the search input element. */
@@ -40,7 +28,28 @@ export interface SearchAutocompleteAria<T> {
   /** Props for the list box, to be passed to [useListBox](useListBox.html). */
   listBoxProps: AriaListBoxOptions<T>,
   /** Props for the search input's clear button. */
-  clearButtonProps: AriaButtonProps
+  clearButtonProps: AriaButtonProps,
+  /** Props for the search autocomplete description element, if any. */
+  descriptionProps: DOMAttributes,
+  /** Props for the search autocomplete error message element, if any. */
+  errorMessageProps: DOMAttributes
+}
+
+export interface AriaSearchAutocompleteOptions<T> extends AriaSearchAutocompleteProps<T> {
+  /** The ref for the input element. */
+  inputRef: RefObject<HTMLInputElement | null>,
+  /** The ref for the list box popover. */
+  popoverRef: RefObject<HTMLDivElement | null>,
+  /** The ref for the list box. */
+  listBoxRef: RefObject<HTMLElement | null>,
+  /** An optional keyboard delegate implementation, to override the default. */
+  keyboardDelegate?: KeyboardDelegate,
+  /**
+   * A delegate object that provides layout information for items in the collection.
+   * By default this uses the DOM, but this can be overridden to implement things like
+   * virtualized scrolling.
+   */
+  layoutDelegate?: LayoutDelegate
 }
 
 /**
@@ -49,42 +58,67 @@ export interface SearchAutocompleteAria<T> {
  * @param props - Props for the search autocomplete.
  * @param state - State for the search autocomplete, as returned by `useSearchAutocomplete`.
  */
-export function useSearchAutocomplete<T>(props: AriaSearchAutocompleteProps<T>, state: ComboBoxState<T>): SearchAutocompleteAria<T> {
+export function useSearchAutocomplete<T>(props: AriaSearchAutocompleteOptions<T>, state: ComboBoxState<T>): SearchAutocompleteAria<T> {
   let {
     popoverRef,
     inputRef,
     listBoxRef,
     keyboardDelegate,
-    onSubmit = () => {}
+    layoutDelegate,
+    onSubmit = () => {},
+    onClear,
+    onKeyDown,
+    onKeyUp,
+    isInvalid,
+    validationState,
+    validationBehavior,
+    isRequired,
+    ...otherProps
   } = props;
 
   let {inputProps, clearButtonProps} = useSearchField({
-    ...props,
+    ...otherProps,
     value: state.inputValue,
     onChange: state.setInputValue,
     autoComplete: 'off',
-    onClear: () => state.setInputValue(''),
+    onClear: () => {
+      state.setInputValue('');
+      if (onClear) {
+        onClear();
+      }
+    },
     onSubmit: (value) => {
       // Prevent submission from search field if menu item was selected
       if (state.selectionManager.focusedKey === null) {
         onSubmit(value, null);
       }
-    } 
+    },
+    onKeyDown,
+    onKeyUp
   }, {
     value: state.inputValue,
     setValue: state.setInputValue
   }, inputRef);
-  
 
-  let {listBoxProps, labelProps, inputProps: comboBoxInputProps} = useComboBox(
+
+  let {listBoxProps, labelProps, inputProps: comboBoxInputProps, ...validation} = useComboBox(
     {
-      ...props,
+      ...otherProps,
       keyboardDelegate,
+      layoutDelegate,
       popoverRef,
       listBoxRef,
       inputRef,
       onFocus: undefined,
-      onBlur: undefined
+      onFocusChange: undefined,
+      onBlur: undefined,
+      onKeyDown: undefined,
+      onKeyUp: undefined,
+      isInvalid,
+      validationState,
+      validationBehavior,
+      isRequired,
+      validate: undefined
     },
     state
   );
@@ -93,6 +127,7 @@ export function useSearchAutocomplete<T>(props: AriaSearchAutocompleteProps<T>,
     labelProps,
     inputProps: mergeProps(inputProps, comboBoxInputProps),
     listBoxProps,
-    clearButtonProps
+    clearButtonProps,
+    ...validation
   };
 }