feat: Async loading support for S2 ComboBox/Picker

package.json

@@ -113,6 +113,7 @@
     "@storybook/addon-themes": "^7.6.19",
     "@storybook/api": "^7.6.19",
     "@storybook/components": "^7.6.19",
+    "@storybook/jest": "^0.2.3",
     "@storybook/manager-api": "^7.6.19",
     "@storybook/preview": "^7.6.19",
     "@storybook/preview-api": "^7.6.19",

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

@@ -103,7 +103,7 @@ export class BaseNode<T> {
   }
 
   private invalidateChildIndices(child: ElementNode<T>): void {
-    if (this._minInvalidChildIndex == null || child.index < this._minInvalidChildIndex.index) {
+    if (this._minInvalidChildIndex == null || !this._minInvalidChildIndex.isConnected || child.index < this._minInvalidChildIndex.index) {
       this._minInvalidChildIndex = child;
     }
   }
@@ -154,8 +154,11 @@ export class BaseNode<T> {
 
     newNode.nextSibling = referenceNode;
     newNode.previousSibling = referenceNode.previousSibling;
-    newNode.index = referenceNode.index;
-
+    // Ensure that the newNode's index is less than that of the reference node so that
+    // invalidateChildIndices will properly use the newNode as the _minInvalidChildIndex, thus making sure
+    // we will properly update the indexes of all sibiling nodes after the newNode. The value here doesn't matter
+    // since updateChildIndices should calculate the proper indexes.
+    newNode.index = referenceNode.index - 1;
     if (this.firstChild === referenceNode) {
       this.firstChild = newNode;
     } else if (referenceNode.previousSibling) {
@@ -165,15 +168,15 @@ export class BaseNode<T> {
     referenceNode.previousSibling = newNode;
     newNode.parentNode = referenceNode.parentNode;
 
-    this.invalidateChildIndices(referenceNode);
+    this.invalidateChildIndices(newNode);
     this.ownerDocument.queueUpdate();
   }
 
   removeChild(child: ElementNode<T>): void {
     if (child.parentNode !== this || !this.ownerDocument.isMounted) {
       return;
     }
-    
+
     if (child.nextSibling) {
       this.invalidateChildIndices(child.nextSibling);
       child.nextSibling.previousSibling = child.previousSibling;
@@ -279,7 +282,7 @@ export class ElementNode<T> extends BaseNode<T> {
       this.node = this.node.clone();
       this.isMutated = true;
     }
-    
+
     this.ownerDocument.markDirty(this);
     return this.node;
   }
@@ -470,6 +473,12 @@ export class Document<T, C extends BaseCollection<T> = BaseCollection<T>> extend
     }
 
     // Next, update dirty collection nodes.
+    // TODO: when updateCollection is called here, shouldn't we be calling this.updateChildIndicies as well? Theoretically it should only update
+    // nodes from _minInvalidChildIndex onwards so the increase in dirtyNodes should be minimal.
+    // Is element.updateNode supposed to handle that (it currently assumes the index stored on the node is correct already).
+    // At the moment, without this call to updateChildIndicies, filtering an async combobox doesn't actually update the index values of the
+    // updated collection...
+    this.updateChildIndices();
     for (let element of this.dirtyNodes) {
       if (element instanceof ElementNode) {
         if (element.isConnected && !element.isHidden) {
@@ -497,7 +506,7 @@ export class Document<T, C extends BaseCollection<T> = BaseCollection<T>> extend
     if (this.dirtyNodes.size === 0 || this.queuedRender) {
       return;
     }
-    
+
     // Only trigger subscriptions once during an update, when the first item changes.
     // React's useSyncExternalStore will call getCollection immediately, to check whether the snapshot changed.
     // If so, React will queue a render to happen after the current commit to our fake DOM finishes.

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

@@ -45,8 +45,11 @@ export {useEffectEvent} from './useEffectEvent';
 export {useDeepMemo} from './useDeepMemo';
 export {useFormReset} from './useFormReset';
 export {useLoadMore} from './useLoadMore';
+export {UNSTABLE_useLoadMoreSentinel} from './useLoadMoreSentinel';
 export {inertValue} from './inertValue';
 export {CLEAR_FOCUS_EVENT, FOCUS_EVENT} from './constants';
 export {isCtrlKeyPressed} from './keyboard';
 export {useEnterAnimation, useExitAnimation} from './animation';
 export {isFocusable, isTabbable} from './isFocusable';
+
+export type {LoadMoreSentinelProps} from './useLoadMoreSentinel';

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

@@ -0,0 +1,64 @@
+/*
+ * 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 type {AsyncLoadable, Collection, Node} from '@react-types/shared';
+import {getScrollParent} from './getScrollParent';
+import {RefObject, useRef} from 'react';
+import {useEffectEvent} from './useEffectEvent';
+import {useLayoutEffect} from './useLayoutEffect';
+
+export interface LoadMoreSentinelProps extends Omit<AsyncLoadable, 'isLoading'> {
+  collection: Collection<Node<unknown>>,
+  /**
+   * The amount of offset from the bottom of your scrollable region that should trigger load more.
+   * Uses a percentage value relative to the scroll body's client height. Load more is then triggered
+   * when your current scroll position's distance from the bottom of the currently loaded list of items is less than
+   * or equal to the provided value. (e.g. 1 = 100% of the scroll region's height).
+   * @default 1
+   */
+  scrollOffset?: number
+  // TODO: Maybe include a scrollRef option so the user can provide the scrollParent to compare against instead of having us look it up
+}
+
+export function UNSTABLE_useLoadMoreSentinel(props: LoadMoreSentinelProps, ref: RefObject<HTMLElement | null>): void {
+  let {collection, onLoadMore, scrollOffset = 1} = props;
+
+  let sentinelObserver = useRef<IntersectionObserver>(null);
+
+  let triggerLoadMore = useEffectEvent((entries: IntersectionObserverEntry[]) => {
+    // Use "isIntersecting" over an equality check of 0 since it seems like there is cases where
+    // a intersection ratio of 0 can be reported when isIntersecting is actually true
+    for (let entry of entries) {
+      // Note that this will be called if the collection changes, even if onLoadMore was already called and is being processed.
+      // Up to user discretion as to how to handle these multiple onLoadMore calls
+      if (entry.isIntersecting && onLoadMore) {
+        onLoadMore();
+      }
+    }
+  });
+
+  useLayoutEffect(() => {
+    if (ref.current) {
+      // Tear down and set up a new IntersectionObserver when the collection changes so that we can properly trigger additional loadMores if there is room for more items
+      // Need to do this tear down and set up since using a large rootMargin will mean the observer's callback isn't called even when scrolling the item into view beause its visibility hasn't actually changed
+      // https://codesandbox.io/p/sandbox/magical-swanson-dhgp89?file=%2Fsrc%2FApp.js%3A21%2C21
+      sentinelObserver.current = new IntersectionObserver(triggerLoadMore, {root: getScrollParent(ref?.current) as HTMLElement, rootMargin: `0px ${100 * scrollOffset}% ${100 * scrollOffset}% ${100 * scrollOffset}%`});
+      sentinelObserver.current.observe(ref.current);
+    }
+
+    return () => {
+      if (sentinelObserver.current) {
+        sentinelObserver.current.disconnect();
+      }
+    };
+  }, [collection, triggerLoadMore, ref, scrollOffset]);
+}

packages/@react-aria/virtualizer/src/ScrollView.tsx

@@ -98,7 +98,6 @@ export function useScrollView(props: ScrollViewProps, ref: RefObject<HTMLElement
       // Prevent rubber band scrolling from shaking when scrolling out of bounds
       state.scrollTop = Math.max(0, Math.min(scrollTop, contentSize.height - state.height));
       state.scrollLeft = Math.max(0, Math.min(scrollLeft, contentSize.width - state.width));
-
       onVisibleRectChange(new Rect(state.scrollLeft, state.scrollTop, state.width, state.height));
 
       if (!state.isScrolling) {
@@ -199,6 +198,7 @@ export function useScrollView(props: ScrollViewProps, ref: RefObject<HTMLElement
 
   // Update visible rect when the content size changes, in case scrollbars need to appear or disappear.
   let lastContentSize = useRef<Size | null>(null);
+  let [update, setUpdate] = useState({});
   useLayoutEffect(() => {
     if (!isUpdatingSize.current && (lastContentSize.current == null || !contentSize.equals(lastContentSize.current))) {
       // React doesn't allow flushSync inside effects, so queue a microtask.
@@ -209,7 +209,11 @@ export function useScrollView(props: ScrollViewProps, ref: RefObject<HTMLElement
       // https://github.com/reactwg/react-18/discussions/102
       // @ts-ignore
       if (typeof IS_REACT_ACT_ENVIRONMENT === 'boolean' ? IS_REACT_ACT_ENVIRONMENT : typeof jest !== 'undefined') {
-        updateSize(fn => fn());
+        // This is so we update size in a separate render but within the same act. Needs to be setState instead of refs
+        // due to strict mode.
+        setUpdate({});
+        lastContentSize.current = contentSize;
+        return;
       } else {
         queueMicrotask(() => updateSize(flushSync));
       }
@@ -218,6 +222,11 @@ export function useScrollView(props: ScrollViewProps, ref: RefObject<HTMLElement
     lastContentSize.current = contentSize;
   });
 
+  // Will only run in tests, needs to be in separate effect so it is properly run in the next render in strict mode.
+  useLayoutEffect(() => {
+    updateSize(fn => fn());
+  }, [update]);
+
   let onResize = useCallback(() => {
     updateSize(flushSync);
   }, [updateSize]);

packages/@react-spectrum/s2/chromatic/Combobox.stories.tsx

@@ -10,15 +10,17 @@
  * governing permissions and limitations under the License.
  */
 
+import {AsyncComboBoxStory, ContextualHelpExample, CustomWidth, Dynamic, EmptyCombobox, Example, Sections, WithIcons} from '../stories/ComboBox.stories';
 import {ComboBox} from '../src';
-import {ContextualHelpExample, CustomWidth, Dynamic, Example, Sections, WithIcons} from '../stories/ComboBox.stories';
+import {expect} from '@storybook/jest';
 import type {Meta, StoryObj} from '@storybook/react';
-import {userEvent, within} from '@storybook/testing-library';
+import {userEvent, waitFor, within} from '@storybook/testing-library';
 
 const meta: Meta<typeof ComboBox<any>> = {
   component: ComboBox,
   parameters: {
-    chromaticProvider: {colorSchemes: ['light'], backgrounds: ['base'], locales: ['en-US'], disableAnimations: true}
+    chromaticProvider: {colorSchemes: ['light'], backgrounds: ['base'], locales: ['en-US'], disableAnimations: true},
+    chromatic: {ignoreSelectors: ['[role="progressbar"]']}
   },
   tags: ['autodocs'],
   title: 'S2 Chromatic/ComboBox'
@@ -69,3 +71,90 @@ export const WithCustomWidth = {
   ...CustomWidth,
   play: async (context) => await Static.play!(context)
 } as StoryObj;
+
+export const WithEmptyState = {
+  ...EmptyCombobox,
+  play: async ({canvasElement}) => {
+    await userEvent.tab();
+    await userEvent.keyboard('{ArrowDown}');
+    let body = canvasElement.ownerDocument.body;
+    let listbox = await within(body).findByRole('listbox');
+    await within(listbox).findByText('No results');
+  }
+};
+
+// TODO: this one is probably not great for chromatic since it has the spinner, check if ignoreSelectors works for it
+export const WithInitialLoading = {
+  ...EmptyCombobox,
+  args: {
+    loadingState: 'loading',
+    label: 'Initial loading'
+  },
+  play: async ({canvasElement}) => {
+    await userEvent.tab();
+    await userEvent.keyboard('{ArrowDown}');
+    let body = canvasElement.ownerDocument.body;
+    let listbox = await within(body).findByRole('listbox');
+    await within(listbox).findByText('Loading', {exact: false});
+  }
+};
+
+export const WithLoadMore = {
+  ...Example,
+  args: {
+    loadingState: 'loadingMore',
+    label: 'Loading more'
+  },
+  play: async ({canvasElement}) => {
+    await userEvent.tab();
+    await userEvent.keyboard('{ArrowDown}');
+    let body = canvasElement.ownerDocument.body;
+    let listbox = await within(body).findByRole('listbox');
+    await within(listbox).findByRole('progressbar');
+  }
+};
+
+export const AsyncResults = {
+  ...AsyncComboBoxStory,
+  args: {
+    ...AsyncComboBoxStory.args,
+    delay: 2000
+  },
+  play: async ({canvasElement}) => {
+    await userEvent.tab();
+    await userEvent.keyboard('{ArrowDown}');
+    let body = canvasElement.ownerDocument.body;
+    let listbox = await within(body).findByRole('listbox');
+    await waitFor(() => {
+      expect(within(listbox).getByText('Luke', {exact: false})).toBeInTheDocument();
+    }, {timeout: 5000});
+  }
+};
+
+export const Filtering = {
+  ...AsyncComboBoxStory,
+  args: {
+    ...AsyncComboBoxStory.args,
+    delay: 2000
+  },
+  play: async ({canvasElement}) => {
+    await userEvent.tab();
+    await userEvent.keyboard('{ArrowDown}');
+    let body = canvasElement.ownerDocument.body;
+    let listbox = await within(body).findByRole('listbox');
+    await waitFor(() => {
+      expect(within(listbox).getByText('Luke', {exact: false})).toBeInTheDocument();
+    }, {timeout: 5000});
+
+    let combobox = await within(body).findByRole('combobox');
+    await userEvent.type(combobox, 'R2');
+
+    await waitFor(() => {
+      expect(within(body).getByRole('progressbar', {hidden: true})).toBeInTheDocument();
+    }, {timeout: 5000});
+
+    await waitFor(() => {
+      expect(within(listbox).queryByRole('progressbar', {hidden: true})).toBeFalsy();
+    }, {timeout: 5000});
+  }
+};

packages/@react-spectrum/s2/chromatic/Picker.stories.tsx

@@ -10,15 +10,17 @@
  * governing permissions and limitations under the License.
  */
 
-import {ContextualHelpExample, CustomWidth, Dynamic, Example, Sections, WithIcons} from '../stories/Picker.stories';
+import {AsyncPickerStory, ContextualHelpExample, CustomWidth, Dynamic, Example, Sections, WithIcons} from '../stories/Picker.stories';
+import {expect} from '@storybook/jest';
 import type {Meta, StoryObj} from '@storybook/react';
 import {Picker} from '../src';
-import {userEvent, within} from '@storybook/testing-library';
+import {userEvent, waitFor, within} from '@storybook/testing-library';
 
 const meta: Meta<typeof Picker<any>> = {
   component: Picker,
   parameters: {
-    chromaticProvider: {colorSchemes: ['light'], backgrounds: ['base'], locales: ['en-US'], disableAnimations: true}
+    chromaticProvider: {colorSchemes: ['light'], backgrounds: ['base'], locales: ['en-US'], disableAnimations: true},
+    chromatic: {ignoreSelectors: ['[role="progressbar"]']}
   },
   tags: ['autodocs'],
   title: 'S2 Chromatic/Picker'
@@ -68,3 +70,58 @@ export const ContextualHelp = {
   }
 };
 
+export const EmptyAndLoading = {
+  render: () => (
+    <Picker label="loading" isLoading>
+      {[]}
+    </Picker>
+  ),
+  play: async ({canvasElement}) => {
+    let body = canvasElement.ownerDocument.body;
+    await waitFor(() => {
+      expect(within(body).getByRole('progressbar', {hidden: true})).toBeInTheDocument();
+    }, {timeout: 5000});
+    await userEvent.tab();
+    await userEvent.keyboard('{ArrowDown}');
+    expect(within(body).queryByRole('listbox')).toBeFalsy();
+  }
+};
+
+export const AsyncResults = {
+  ...AsyncPickerStory,
+  args: {
+    ...AsyncPickerStory.args,
+    delay: 2000
+  },
+  play: async ({canvasElement}) => {
+    let body = canvasElement.ownerDocument.body;
+    await waitFor(() => {
+      expect(within(body).getByRole('progressbar', {hidden: true})).toBeInTheDocument();
+    }, {timeout: 5000});
+    await userEvent.tab();
+
+    await waitFor(() => {
+      expect(within(body).queryByRole('progressbar', {hidden: true})).toBeFalsy();
+    }, {timeout: 5000});
+
+    await userEvent.keyboard('{ArrowDown}');
+    let listbox = await within(body).findByRole('listbox');
+    await waitFor(() => {
+      expect(within(listbox).getByText('Luke', {exact: false})).toBeInTheDocument();
+    }, {timeout: 5000});
+
+    await waitFor(() => {
+      expect(within(listbox).getByRole('progressbar', {hidden: true})).toBeInTheDocument();
+    }, {timeout: 5000});
+
+    await waitFor(() => {
+      expect(within(listbox).queryByRole('progressbar', {hidden: true})).toBeFalsy();
+    }, {timeout: 5000});
+
+    await userEvent.keyboard('{PageDown}');
+
+    await waitFor(() => {
+      expect(within(listbox).getByText('Greedo', {exact: false})).toBeInTheDocument();
+    }, {timeout: 5000});
+  }
+};

packages/@react-spectrum/s2/intl/ar-AE.json

@@ -6,6 +6,7 @@
   "actionbar.selectedAll": "تم تحديد الكل",
   "breadcrumbs.more": "المزيد من العناصر",
   "button.pending": "قيد الانتظار",
+  "combobox.noResults": "لا توجد نتائج",
   "contextualhelp.help": "مساعدة",
   "contextualhelp.info": "معلومات",
   "dialog.alert": "تنبيه",