feat: Add Autocomplete wrapper for Menu and ListBox #7181

LFDanLu · 2024-10-11T21:52:47Z

Closes

#7248 has a version that always persists focus, to test on Monday

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

🧢 Your Project:

RSP

issues outlined in various comments, basically boils down to ideally using the wrapped collection components state

rspbot · 2024-10-11T22:18:38Z

Build successful! 🎉

packages/react-aria-components/src/Menu.tsx

packages/react-aria-components/src/Autocomplete.tsx

ended up going with dispatching events to the menu/menuitem so we can piggyback off of useSelectableCollection and menus press handling for submenutriggers, onAction, and link handling

rspbot · 2024-10-23T22:02:19Z

Build successful! 🎉

rspbot · 2024-10-24T00:32:06Z

Build successful! 🎉

packages/@react-aria/autocomplete/intl/ar-AE.json

packages/@react-aria/autocomplete/src/useAutocomplete.ts

rspbot · 2024-10-24T18:07:59Z

Build successful! 🎉

packages/@react-aria/autocomplete/src/useAutocomplete.ts

LFDanLu · 2024-10-24T18:15:17Z

packages/@react-aria/collections/src/BaseCollection.ts

+  // TODO: this is pretty specific to menu, will need to check if it is generic enough
+  // Will need to handle varying levels I assume but will revisit after I get searchable menu working for base menu
+  // TODO: an alternative is to simply walk the collection and add all item nodes that match the filter and any sections/separators we encounter
+  // to an array, then walk that new array and fix all the next/Prev keys while adding them to the new collection
+  filter(filterFn: (nodeValue: string) => boolean): BaseCollection<T> {


Definitely specific to menu, will need to update when we handle other collection components. Collections is in alpha so that should shield us from any changes that may need to happen to this function

rspbot · 2024-11-23T00:45:43Z

Build successful! 🎉

rspbot · 2024-11-23T00:57:40Z

Build successful! 🎉

LFDanLu · 2024-11-25T18:24:59Z

packages/@react-aria/autocomplete/src/useAutocomplete.ts

+      spellCheck: 'false'
+    },
+    collectionProps: mergeProps(collectionProps, {
+      // TODO: shouldFocusOnHover?


wonder if it might make sense to change focus on hover by default for the wrapped collection

rspbot · 2024-11-25T18:29:47Z

Build successful! 🎉

packages/@react-aria/autocomplete/src/useAutocomplete.ts

LFDanLu · 2024-11-26T01:22:07Z

packages/@react-aria/selection/src/useSelectableItem.ts

+      // TODO: non ideal since this makes the link action happen on press start rather than on press up like it usually
+      // does for listboxes but we never get the onPress event because the simiulated event target from useAutocomplete is different
+      // from the actual place it is triggered from (the input).
+      if (shouldUseVirtualFocus && e.pointerType === 'keyboard' && hasAction) {
+        performAction(e);
+      }


Not sure if there is a better way to go about this here. As described above the simulated event from useAutocomplete doesn't actually cause onPress to be triggered because the tracked state.target (listbox item) in usePress doesn't match/contain the event target's original target (the autocomplete input) but ideally we'd want links to be triggered on key up like they usually are for listboxes

Hm, would there be issues with moving the focus briefly with requestAnimationFrame(), similar to what we do with tabindex in useGridCell?

As in moving focus to the virtually focused item on Enter press, then dispatching the keydown event so that the event target for both the keydown/up is the focused item? That can certainly work but it does mean there will be a blur event on the input element that could be unexpected for the end user since this is supposed to be virtual focus.

Additionally, if there any cases where we'd want to return focus back to the input after the focus movement to the item, it might lead to some unexpected/noisy screenreader announcements in addition to these extra blur events, will have to test. As an aside, supporting wrapping a GridList/Table is also going to be interesting because we'd want grid navigation to work but left/right arrow is going to also move the text cursor in the field and clear virtual focus for NVDA announcements... It may turn out that ditching virtual focus is easier tbh, and perhaps the user should just tab between the input and the wrapped collection

Yep, I intended to always reset the focus back to the input on the next frame 👍

The blur events would indeed be an annoying side-effect, but we might be able to early return if we delay onBlur callback invocations to the next frame as well. Surely feels like fighting an uphill battle though.

Very interesting that autocomplete is planned to make its way over to grids eventually as well. Will follow the development on this closely 😄

rspbot · 2024-11-26T01:28:20Z

Build successful! 🎉

LFDanLu · 2024-11-26T18:08:44Z

packages/react-aria-components/src/SearchField.tsx

@@ -55,6 +55,7 @@ function SearchField(props: SearchFieldProps, ref: ForwardedRef<HTMLDivElement>)
  let {validationBehavior: formValidationBehavior} = useSlottedContext(FormContext) || {};
  let validationBehavior = props.validationBehavior ?? formValidationBehavior ?? 'native';
  let inputRef = useRef<HTMLInputElement>(null);
+  let [inputContextProps, mergedInputRef] = useContextProps({}, inputRef, InputContext);


Note this opens up the ability for the user to influence the TextField's input from outside the textfield now

a bit weird, since this is the only place where we merge contexts instead of having the deepest one win, but otherwise we have to make Autocomplete provide the contexts for SearchField, TextField, TextArea, and all other possible fields which doesn't seem so sustainable...

yeah, I was a bit torn here. I guess one down side of the current approach is that you'd need to remember to clear the context if there were input props from a higher level context that you didn't want...

devongovett

Awesome work! So excited about this.

packages/@react-aria/autocomplete/src/useAutocomplete.ts

devongovett · 2024-11-26T20:43:23Z

packages/@react-aria/autocomplete/src/useAutocomplete.ts

+  // 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
+  let lastInputValue = useRef<string | null>(null);
+  useEffect(() => {


Any chance this can be done in an event (e.g. onChange) rather than an effect? Seems like that would be more explicit about the intent (the user typed something, not a result of some external state update).

when I changed this to onChange in an attempt to have the input value be managed at the input level instead, I ran into the problem where focusFirstItem was firing before the collection filtered itself in response and thus was getting the incorrect activedescendant id. I'll try this again now that the input text is managed at the top level again

yep, if I use onChange here the focusFirstItem happens before the collection is filtered in response to the change in input value.

packages/@react-aria/autocomplete/src/useAutocomplete.ts

devongovett · 2024-11-26T20:50:06Z

packages/@react-aria/autocomplete/src/useAutocomplete.ts

+        new KeyboardEvent(e.nativeEvent.type, e.nativeEvent)
+      );
+      // TODO: this currently has problems making Enter trigger Listbox links. usePress catches the press up that happens but
+      // detects that the press target is different from the event target aka listbox item vs the input where the Enter event occurs...


Do we need to forward onKeyUp to the target as well?

I had thought that was the reason when I ran into this yesterday, but it didn't seem to change anything, the keyup event in usePress still detects that the event target of the keyup is the input. I assumed that stopping propagation on keydown would've allowed the dispatched keyup event to make it to usePress and fake that the keyup was happening on the option rather than the input but no luck

I guess because the key up event on the input happens first. Maybe capturing listener would work?

unfortunately making the onKeyUp a capturing listener didn't seem to help, the event on the input still happened first it seems. Changing the capturing listener for onKeyUp in usePress to non-capturing did fix it but we rely on it being capturing...

devongovett · 2024-11-26T20:52:03Z

packages/@react-aria/autocomplete/src/useAutocomplete.ts

+      shouldUseVirtualFocus: true,
+      disallowTypeAhead: true
+    }),
+    collectionRef: mergedCollectionRef,


a bit strange to return refs from a hook, but I guess in this case we need a callback ref so not sure how else we'd handle it...

packages/@react-aria/selection/src/useSelectableCollection.ts

devongovett · 2024-11-26T20:59:57Z

packages/@react-aria/utils/src/constants.ts

+// Custom event names for updating the autocomplete's aria-activedecendant.
+export const CLEAR_FOCUS_EVENT = 'react-aria-clear-focus';
+export const FOCUS_EVENT = 'react-aria-focus';
+export const UPDATE_ACTIVEDESCENDANT = 'react-aria-update-activedescendant';


Should these go in the @react-aria/selection package since they are mainly specific to that?

I had considered that but it felt weird to import that package into @react-aria/autocomplete when there isn't anything selection related going on per say. If anything, I wish there was a even lower level hook than useSelectableCollection/useSelectableItem to put all this virtual focus stuff in since they aren't explicitly selection related.

Happy to move these into @react-aria/selection based on what people think but it just felt like @react-aria/utils was broader place to store these for now

devongovett · 2024-11-26T21:02:34Z

packages/react-aria-components/src/Menu.tsx

+  // TODO: Since menu only has `items` and not `defaultItems`, this means the user can't have completly controlled items like in ComboBox,
+  // we always perform the filtering for them.
+  let filteredCollection = useMemo(() => filterFn ? collection.filter(filterFn) : collection, [collection, filterFn]);


I was gonna ask about this. Seems less common for menu, but if someone wanted to create a SearchAutocomplete-like component with RAC, they'd probably want to be able to control the filtered items from the server.

devongovett · 2024-11-26T21:03:31Z

packages/react-aria-components/src/SearchField.tsx

@@ -55,6 +55,7 @@ function SearchField(props: SearchFieldProps, ref: ForwardedRef<HTMLDivElement>)
  let {validationBehavior: formValidationBehavior} = useSlottedContext(FormContext) || {};
  let validationBehavior = props.validationBehavior ?? formValidationBehavior ?? 'native';
  let inputRef = useRef<HTMLInputElement>(null);
+  let [inputContextProps, mergedInputRef] = useContextProps({}, inputRef, InputContext);


a bit weird, since this is the only place where we merge contexts instead of having the deepest one win, but otherwise we have to make Autocomplete provide the contexts for SearchField, TextField, TextArea, and all other possible fields which doesn't seem so sustainable...

devongovett

Oops didn't mean to approve yet. Too excited!

packages/@react-aria/menu/src/index.ts

packages/@react-aria/menu/src/utils.ts

packages/@react-aria/menu/src/useMenuItem.ts

snowystinger · 2024-11-26T21:42:05Z

packages/@react-aria/selection/src/useSelectableItem.ts

-      } else if (document.activeElement !== ref.current && ref.current) {
-        focusSafely(ref.current);
+    if (isFocused && manager.isFocused) {
+      if (!shouldUseVirtualFocus) {


not for this PR, but possible improvement I'd like to discuss. since we now fire our own custom event, I wonder if we could always do that and make these hooks agnostic of focusing. I think we could do away with a lot of these checks for 'shouldUseVirtualFocus' in hooks that don't really need to know about virtualizers at all, or focus for that matter.

I do feel like useSelectableCollection handles too much for sure, definitely can discuss this further

packages/react-aria-components/test/AriaAutocomplete.test-util.tsx

rspbot · 2024-11-27T19:31:43Z

Build successful! 🎉

snowystinger · 2024-11-27T21:35:20Z

packages/react-aria-components/test/AriaAutocomplete.test-util.tsx

+          let options = within(menu).getAllByRole(collectionItemRole);
+          expect(input).toHaveAttribute('aria-activedescendant', options[0].id);
+          await user.keyboard('{Enter}');
+          expect(actionListener).toHaveBeenCalledTimes(1);


better, however, this is still tied to our API.
Someone could implement an autocomplete that is self contained and fires no event (I'm not sure why, but they could, maybe they fire a custom event on the dom instead of using props)

In addition, they may not include the id of the item, maybe they've created some mapping of the ids to some database uuid or something.

The actionListener here that they provided doesn't have to be passed to component via props though, they just need to provide us with whatever action listener mock that would get triggered on item action and we assert it has been properly called when hitting enter on the input while that item is focused right?

As for the id of the item, the id being checked above is the aria-activedescendant which needs to be tied to the dom node they are virtually focusing so that should be fine as well right?

rspbot · 2024-11-27T23:01:23Z

Build successful! 🎉

rspbot · 2024-11-27T23:01:24Z

## API Changes

react-aria-components

/react-aria-components:Autocomplete

+Autocomplete {
+  children: ReactNode
+  defaultFilter?: (string, string) => boolean = contains
+  defaultInputValue?: string
+  inputValue?: string
+  onInputChange?: (string) => void
+  slot?: string | null
+}

/react-aria-components:AutocompleteContext

+AutocompleteContext {
+  UNTYPED
+}

/react-aria-components:AutocompleteStateContext

+AutocompleteStateContext {
+  UNTYPED
+}

/react-aria-components:InternalAutocompleteContext

+InternalAutocompleteContext {
+  UNTYPED
+}

@react-aria/autocomplete

/@react-aria/autocomplete:useAutocomplete

+useAutocomplete {
+  props: AriaAutocompleteOptions
+  state: AutocompleteState
+  returnVal: undefined
+}

/@react-aria/autocomplete:AriaAutocompleteProps

+AriaAutocompleteProps {
+  children: ReactNode
+  defaultFilter?: (string, string) => boolean = contains
+  defaultInputValue?: string
+  inputValue?: string
+  onInputChange?: (string) => void
+}

/@react-aria/autocomplete:AriaAutocompleteOptions

+AriaAutocompleteOptions {
+  collectionRef: RefObject<HTMLElement | null>
+  defaultFilter?: (string, string) => boolean = contains
+  defaultInputValue?: string
+  inputValue?: string
+  onInputChange?: (string) => void
+}

/@react-aria/autocomplete:AutocompleteAria

+AutocompleteAria {
+  collectionProps: CollectionOptions
+  collectionRef: RefObject<HTMLElement | null>
+  filterFn: (string) => boolean
+  inputProps: InputHTMLAttributes<HTMLInputElement>
+}

/@react-aria/autocomplete:CollectionOptions

+CollectionOptions {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  disallowTypeAhead: boolean
+  id?: string
+  shouldUseVirtualFocus: boolean
+}

@react-aria/collections

/@react-aria/collections:BaseCollection

 BaseCollection <T> {
   addNode: (CollectionNode<T>) => void
   at: () => Node<T>
   clone: () => this
   commit: (Key | null, Key | null, any) => void
+  filter: ((string) => boolean) => BaseCollection<T>
   getChildren: (Key) => Iterable<Node<T>>
   getFirstKey: () => void
   getItem: (Key) => Node<T> | null
   getKeyAfter: (Key) => void
   getKeys: () => void
   getLastKey: () => void
   removeNode: (Key) => void
   size: any
   undefined: () => void
 }

@react-aria/menu

/@react-aria/menu:AriaMenuOptions

 AriaMenuOptions <T> {
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean | FocusStrategy
   defaultSelectedKeys?: 'all' | Iterable<Key>
   disabledKeys?: Iterable<Key>
   disallowEmptySelection?: boolean
   id?: string
   isVirtualized?: boolean
   items?: Iterable<T>
   keyboardDelegate?: KeyboardDelegate
   onAction?: (Key) => void
   onClose?: () => void
   onKeyDown?: (KeyboardEvent) => void
   onKeyUp?: (KeyboardEvent) => void
   onSelectionChange?: (Selection) => void
   selectedKeys?: 'all' | Iterable<Key>
   selectionMode?: SelectionMode
   shouldFocusWrap?: boolean
+  shouldUseVirtualFocus?: boolean
 }

@react-aria/selection

/@react-aria/selection:SelectableItemOptions

 SelectableItemOptions {
   allowsDifferentPressOrigin?: boolean
   focus?: () => void
+  id?: string
   isDisabled?: boolean
   isVirtualized?: boolean
   key: Key
   linkBehavior?: 'action' | 'selection' | 'override' | 'none' = 'action'
   ref: RefObject<FocusableElement | null>
   selectionManager: MultipleSelectionManager
   shouldSelectOnPressUp?: boolean
   shouldUseVirtualFocus?: boolean
 }

@react-aria/utils

/@react-aria/utils:CLEAR_FOCUS_EVENT

+CLEAR_FOCUS_EVENT {
+  UNTYPED
+}

/@react-aria/utils:FOCUS_EVENT

+FOCUS_EVENT {
+  UNTYPED
+}

/@react-aria/utils:UPDATE_ACTIVEDESCENDANT

+UPDATE_ACTIVEDESCENDANT {
+  UNTYPED
+}

@react-stately/autocomplete

/@react-stately/autocomplete:useAutocompleteState

+useAutocompleteState {
+  props: AutocompleteStateOptions
+  returnVal: undefined
+}

/@react-stately/autocomplete:AutocompleteProps

+AutocompleteProps {
+  children: ReactNode
+  defaultInputValue?: string
+  inputValue?: string
+  onInputChange?: (string) => void
+}

/@react-stately/autocomplete:AutocompleteStateOptions

+AutocompleteStateOptions {
+  defaultInputValue?: string
+  inputValue?: string
+  onInputChange?: (string) => void
+}

/@react-stately/autocomplete:AutocompleteState

+AutocompleteState {
+  focusedNodeId: string | null
+  inputValue: string
+  setFocusedNodeId: (string | null) => void
+  setInputValue: (string) => void
+}

LFDanLu added 6 commits October 9, 2024 14:22

scaffolding, copied Combobox and renamed to Autocomplete

c33ac96

get listbox rendering by default without open state

a185473

update intl file and more clean up to get rid of combobox stuff

e6fa7c1

fix lint

61aab83

rough working version of Menu instead of Listbox in autocomplete

66fecc8

issues outlined in various comments, basically boils down to ideally using the wrapped collection components state

fix submenu

779309b

LFDanLu commented Oct 11, 2024

View reviewed changes

packages/react-aria-components/src/Menu.tsx Outdated Show resolved Hide resolved

LFDanLu commented Oct 15, 2024

View reviewed changes

packages/react-aria-components/src/Autocomplete.tsx Outdated Show resolved Hide resolved

LFDanLu added the in sprint label Oct 16, 2024

LFDanLu added 6 commits October 18, 2024 17:20

Update autocomplete to have the wrapped menu filter itself

78de7f8

fix keyboard interactions, and clean up

e0f098a

ended up going with dispatching events to the menu/menuitem so we can piggyback off of useSelectableCollection and menus press handling for submenutriggers, onAction, and link handling

fix menu, add more stories, fix strict

5914d11

add announcements to menu and various clean up

12480fd

update yarn.lock

ad8942a

Merge branch 'main' of github.com:adobe/react-spectrum into autocomplete

70c2d0f

adobe deleted a comment from rspbot Oct 22, 2024

LFDanLu added 3 commits October 23, 2024 11:55

get rid of dom node in Autocomplete and fix readOnly bugs

9812c3c

fix build failure

8478937

test against popover experience

3fbd35f

fix popover story

e15d999

properly clear aria-activedecendant

368a677

LFDanLu commented Oct 24, 2024

View reviewed changes

packages/@react-aria/autocomplete/intl/ar-AE.json Outdated Show resolved Hide resolved

LFDanLu commented Oct 24, 2024

View reviewed changes

packages/@react-aria/autocomplete/src/useAutocomplete.ts Outdated Show resolved Hide resolved

LFDanLu commented Oct 24, 2024

View reviewed changes

packages/@react-aria/autocomplete/src/useAutocomplete.ts Outdated Show resolved Hide resolved

LFDanLu commented Oct 24, 2024

View reviewed changes

packages/@react-aria/autocomplete/src/useAutocomplete.ts Outdated Show resolved Hide resolved

LFDanLu commented Oct 24, 2024

View reviewed changes

LFDanLu added 2 commits November 22, 2024 16:47

fix listbox test

0757832

Merge branch 'main' of github.com:adobe/react-spectrum into autocomplete

fd709a2

LFDanLu marked this pull request as ready for review November 23, 2024 00:54

LFDanLu changed the title ~~(WIP) Autocomplete with menu~~ Add Autocomplete wrapper for Menu and ListBox Nov 23, 2024

LFDanLu changed the title ~~Add Autocomplete wrapper for Menu and ListBox~~ feat: Add Autocomplete wrapper for Menu and ListBox Nov 23, 2024

LFDanLu added 2 commits November 22, 2024 17:39

fix build and react 19

9eede0c

get rid of leftover react 19 testing changes

6bd5270

LFDanLu commented Nov 25, 2024

View reviewed changes

clean up some todos

150bd7e

LFDanLu commented Nov 25, 2024

View reviewed changes

packages/@react-aria/autocomplete/src/useAutocomplete.ts Outdated Show resolved Hide resolved

LFDanLu added 2 commits November 25, 2024 15:17

fix listbox listeners not registering

c13544b

updating tests and making enter trigger listbox link

0d68f68

LFDanLu commented Nov 26, 2024

View reviewed changes

devongovett approved these changes Nov 26, 2024

View reviewed changes

devongovett requested changes Nov 26, 2024

View reviewed changes

snowystinger reviewed Nov 26, 2024

View reviewed changes

LFDanLu added 3 commits November 26, 2024 14:58

initial review comments

d8c5259

update tests and remove menu id coercing in favor of user defined ids

00f67ad

fix lock

1a26d79

snowystinger reviewed Nov 27, 2024

View reviewed changes

LFDanLu added 2 commits November 27, 2024 14:43

Merge branch 'main' of github.com:adobe/react-spectrum into autocomplete

435c6dc

update forward ref for react fast refresh

df03339

feat: Add Autocomplete wrapper for Menu and ListBox #7181

Are you sure you want to change the base?

feat: Add Autocomplete wrapper for Menu and ListBox #7181

Conversation

LFDanLu commented Oct 11, 2024 • edited Loading

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

rspbot commented Oct 11, 2024

rspbot commented Oct 23, 2024

rspbot commented Oct 24, 2024

rspbot commented Oct 24, 2024

Choose a reason for hiding this comment

rspbot commented Nov 23, 2024

rspbot commented Nov 23, 2024

Choose a reason for hiding this comment

rspbot commented Nov 25, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rspbot commented Nov 26, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

devongovett left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

devongovett left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rspbot commented Nov 27, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rspbot commented Nov 27, 2024

rspbot commented Nov 27, 2024

react-aria-components

/react-aria-components:Autocomplete

/react-aria-components:AutocompleteContext

/react-aria-components:AutocompleteStateContext

/react-aria-components:InternalAutocompleteContext

@react-aria/autocomplete

/@react-aria/autocomplete:useAutocomplete

/@react-aria/autocomplete:AriaAutocompleteProps

/@react-aria/autocomplete:AriaAutocompleteOptions

/@react-aria/autocomplete:AutocompleteAria

/@react-aria/autocomplete:CollectionOptions

@react-aria/collections

/@react-aria/collections:BaseCollection

@react-aria/menu

/@react-aria/menu:AriaMenuOptions

@react-aria/selection

/@react-aria/selection:SelectableItemOptions

@react-aria/utils

/@react-aria/utils:CLEAR_FOCUS_EVENT

/@react-aria/utils:FOCUS_EVENT

/@react-aria/utils:UPDATE_ACTIVEDESCENDANT

@react-stately/autocomplete

/@react-stately/autocomplete:useAutocompleteState

/@react-stately/autocomplete:AutocompleteProps

/@react-stately/autocomplete:AutocompleteStateOptions

/@react-stately/autocomplete:AutocompleteState

LFDanLu commented Oct 11, 2024 •

edited

Loading