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

Author: LFDanLu

packages/@internationalized/date/docs/CalendarDate.mdx

@@ -72,7 +72,7 @@ date.toString(); // '2022-02-03'
 
 By default, `CalendarDate` uses the Gregorian calendar system, but many other calendar systems that are used around the world are supported, such as Hebrew, Indian, Islamic, Buddhist, Ethiopic, and more. A <TypeLink links={docs.links} type={docs.exports.Calendar} /> instance can be passed to the `CalendarDate` constructor to represent dates in that calendar system.
 
-This example creates a date in the Buddhist calendar system, which is equivalent to April 4th, 2020 in the Gregorian calendar.
+This example creates a date in the Buddhist calendar system, which is equivalent to April 30th, 2020 in the Gregorian calendar.
 
 ```tsx
 import {BuddhistCalendar} from '@internationalized/date';
@@ -86,7 +86,7 @@ See the [Calendar](Calendar.html#implementations) docs for details about the sup
 
 Many calendar systems have only one era, or a modern era and a pre-modern era (e.g. AD and BC in the Gregorian calendar). However, other calendar systems may have many eras. For example, the Japanese calendar has eras for the reign of each Emperor. `CalendarDate` represents eras using string identifiers, which can be passed as an additional parameter to the constructor before the year. When eras are present, years are numbered starting from 1 within the era.
 
-This example creates a date in the Japanese calendar system, which is equivalent to April 4th, 2020 in the Gregorian calendar.
+This example creates a date in the Japanese calendar system, which is equivalent to April 30th, 2019 in the Gregorian calendar.
 
 ```tsx
 import {JapaneseCalendar} from '@internationalized/date';

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

@@ -460,9 +460,13 @@ export class Document<T, C extends BaseCollection<T> = BaseCollection<T>> extend
   }
 
   updateCollection(): void {
-    // First, update the indices of dirty element children.
+    // First, remove disconnected nodes and update the indices of dirty element children.
     for (let element of this.dirtyNodes) {
-      element.updateChildIndices();
+      if (element instanceof ElementNode && (!element.isConnected || element.isHidden)) {
+        this.removeNode(element);
+      } else {
+        element.updateChildIndices();
+      }
     }
 
     // Next, update dirty collection nodes.
@@ -471,8 +475,6 @@ export class Document<T, C extends BaseCollection<T> = BaseCollection<T>> extend
         if (element.isConnected && !element.isHidden) {
           element.updateNode();
           this.addNode(element);
-        } else {
-          this.removeNode(element);
         }
 
         element.isMutated = false;

packages/@react-aria/grid/src/useGrid.ts

@@ -53,7 +53,16 @@ export interface GridProps extends DOMProps, AriaLabelingProps {
   /** Handler that is called when a user performs an action on the row. */
   onRowAction?: (key: Key) => void,
   /** Handler that is called when a user performs an action on the cell. */
-  onCellAction?: (key: Key) => void
+  onCellAction?: (key: Key) => void,
+  /**
+   * Whether pressing the escape key should clear selection in the grid or not.
+   *
+   * Most experiences should not modify this option as it eliminates a keyboard user's ability to
+   * easily clear selection. Only use if the escape key is being handled externally or should not
+   * trigger selection clearing contextually.
+   * @default 'clearSelection'
+   */
+  escapeKeyBehavior?: 'clearSelection' | 'none'
 }
 
 export interface GridAria {
@@ -77,7 +86,8 @@ export function useGrid<T>(props: GridProps, state: GridState<T, GridCollection<
     scrollRef,
     getRowText,
     onRowAction,
-    onCellAction
+    onCellAction,
+    escapeKeyBehavior = 'clearSelection'
   } = props;
   let {selectionManager: manager} = state;
 
@@ -106,7 +116,8 @@ export function useGrid<T>(props: GridProps, state: GridState<T, GridCollection<
     keyboardDelegate: delegate,
     isVirtualized,
     scrollRef,
-    disallowTypeAhead
+    disallowTypeAhead,
+    escapeKeyBehavior
   });
 
   let id = useId(props.id);

packages/@react-aria/gridlist/src/useGridList.ts

@@ -48,7 +48,16 @@ export interface AriaGridListProps<T> extends GridListProps<T>, DOMProps, AriaLa
    * via the left/right arrow keys or the tab key.
    * @default 'arrow'
    */
-  keyboardNavigationBehavior?: 'arrow' | 'tab'
+  keyboardNavigationBehavior?: 'arrow' | 'tab',
+  /**
+   * Whether pressing the escape key should clear selection in the grid list or not.
+   *
+   * Most experiences should not modify this option as it eliminates a keyboard user's ability to
+   * easily clear selection. Only use if the escape key is being handled externally or should not
+   * trigger selection clearing contextually.
+   * @default 'clearSelection'
+   */
+  escapeKeyBehavior?: 'clearSelection' | 'none'
 }
 
 export interface AriaGridListOptions<T> extends Omit<AriaGridListProps<T>, 'children'> {
@@ -105,7 +114,8 @@ export function useGridList<T>(props: AriaGridListOptions<T>, state: ListState<T
     onAction,
     disallowTypeAhead,
     linkBehavior = 'action',
-    keyboardNavigationBehavior = 'arrow'
+    keyboardNavigationBehavior = 'arrow',
+    escapeKeyBehavior = 'clearSelection'
   } = props;
 
   if (!props['aria-label'] && !props['aria-labelledby']) {
@@ -124,7 +134,8 @@ export function useGridList<T>(props: AriaGridListOptions<T>, state: ListState<T
     shouldFocusWrap: props.shouldFocusWrap,
     linkBehavior,
     disallowTypeAhead,
-    autoFocus: props.autoFocus
+    autoFocus: props.autoFocus,
+    escapeKeyBehavior
   });
 
   let id = useId(props.id);

packages/@react-aria/interactions/src/useMove.ts

@@ -93,7 +93,7 @@ export function useMove(props: MoveEvents): MoveResult {
       state.current.didMove = false;
     };
 
-    if (typeof PointerEvent === 'undefined') {
+    if (typeof PointerEvent === 'undefined' && process.env.NODE_ENV === 'test') {
       let onMouseMove = (e: MouseEvent) => {
         if (e.button === 0) {
           move(e, 'mouse', e.pageX - (state.current.lastPosition?.pageX ?? 0), e.pageY - (state.current.lastPosition?.pageY ?? 0));
@@ -151,7 +151,7 @@ export function useMove(props: MoveEvents): MoveResult {
         addGlobalListener(window, 'touchend', onTouchEnd, false);
         addGlobalListener(window, 'touchcancel', onTouchEnd, false);
       };
-    } else if (process.env.NODE_ENV === 'test') {
+    } else {
       let onPointerMove = (e: PointerEvent) => {
         if (e.pointerId === state.current.id) {
           let pointerType = (e.pointerType || 'mouse') as PointerType;

packages/@react-aria/overlays/docs/PortalProvider.mdx

@@ -0,0 +1,138 @@
+{/* Copyright 2025 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 {Layout} from '@react-spectrum/docs';
+export default Layout;
+
+import docs from 'docs:@react-aria/overlays';
+import {HeaderInfo, PropTable, FunctionAPI, PageDescription} from '@react-spectrum/docs';
+import packageData from '@react-aria/overlays/package.json';
+
+---
+category: Utilities
+keywords: [overlays, portals]
+---
+
+# PortalProvider
+
+<PageDescription>{docs.exports.UNSAFE_PortalProvider.description}</PageDescription>
+
+<HeaderInfo
+  packageData={packageData}
+  componentNames={['UNSAFE_PortalProvider', 'useUNSAFE_PortalContext']} />
+
+## Introduction
+
+`UNSAFE_PortalProvider` is a utility wrapper component that can be used to set where components like
+Modals, Popovers, Toasts, and Tooltips will portal their overlay element to. This is typically used when
+your app is already portalling other elements to a location other than the `document.body` and thus requires
+your React Aria components to send their overlays to the same container.
+
+Please note that `UNSAFE_PortalProvider` is considered `UNSAFE` because it is an escape hatch, and there are
+many places that an application could portal to. Not all of them will work, either with styling, accessibility,
+or for a variety of other reasons. Typically, it is best to portal to the root of the entire application, e.g. the `body` element,
+outside of any possible overflow or stacking contexts. We envision `UNSAFE_PortalProvider` being used to group all of the portalled
+elements into a single container at the root of the app or to control the order of children of the `body` element, but you may have use cases
+that need to do otherwise.
+
+## Props
+
+<PropTable links={docs.links} component={docs.exports.UNSAFE_PortalProvider} />
+
+## Example
+
+The example below shows how you can use `UNSAFE_PortalProvider` to portal your Toasts to an arbitrary container. Note that
+the Toast in this example is taken directly from the [React Aria Components Toast documentation](Toast.html#example), please visit that page for
+a detailed explanation of its implementation.
+
+```tsx import
+import {UNSTABLE_ToastRegion as ToastRegion, UNSTABLE_Toast as Toast, UNSTABLE_ToastQueue as ToastQueue, UNSTABLE_ToastContent as ToastContent, Button, Text} from 'react-aria-components';
+
+
+// Define the type for your toast content.
+interface MyToastContent {
+  title: string,
+  description?: string
+}
+
+// Create a global ToastQueue.
+const queue = new ToastQueue<MyToastContent>();
+
+function MyToastRegion() {
+  return (
+    <ToastRegion queue={queue}>
+      {({toast}) => (
+        <Toast toast={toast}>
+          <ToastContent>
+            <Text slot="title">{toast.content.title}</Text>
+            <Text slot="description">{toast.content.description}</Text>
+          </ToastContent>
+          <Button slot="close">x</Button>
+        </Toast>
+      )}
+    </ToastRegion>
+
+  );
+}
+```
+
+```tsx example
+import {UNSAFE_PortalProvider} from '@react-aria/overlays';
+
+// See the above Toast docs link for the ToastRegion implementation
+function App() {
+  let container = React.useRef(null);
+  return (
+    <>
+      <UNSAFE_PortalProvider getContainer={() => container.current}>
+        <MyToastRegion />
+        <Button
+          onPress={() => queue.add({
+            title: 'Toast complete!',
+            description: 'Great success.'
+          })}>
+          Open Toast
+        </Button>
+      </UNSAFE_PortalProvider>
+      <div ref={container} style={{height: '110px', width: '200px',  overflow: 'auto', display: 'flex', flexDirection: 'column', gap: '20px', padding: '5px'}}>
+        Toasts are portalled here!
+      </div>
+    </>
+  );
+}
+
+<App />
+```
+
+```css hidden
+@import '../../../react-aria-components/docs/Button.mdx' layer(button);
+@import '../../../react-aria-components/docs/Toast.mdx' layer(toast);
+@import "@react-aria/example-theme";
+
+.react-aria-ToastRegion {
+  position: unset;
+}
+```
+
+## Contexts
+
+The `getContainer` set by the nearest PortalProvider can be accessed by calling `useUNSAFE_PortalContext`. This can be
+used by custom overlay components to ensure that they are also being consistently portalled throughout your app.
+
+<FunctionAPI links={docs.links} function={docs.exports.useUNSAFE_PortalContext} />
+
+```tsx
+import {useUNSAFE_PortalContext} from '@react-aria/overlays';
+
+function MyOverlay(props) {
+  let {children} = props;
+  let {getContainer} = useUNSAFE_PortalContext();
+  return ReactDOM.createPortal(children, getContainer());
+}
+```

packages/@react-aria/overlays/src/Overlay.tsx

@@ -16,12 +16,13 @@ import React, {ReactNode, useContext, useMemo, useState} from 'react';
 import ReactDOM from 'react-dom';
 import {useIsSSR} from '@react-aria/ssr';
 import {useLayoutEffect} from '@react-aria/utils';
-import {useUNSTABLE_PortalContext} from './PortalProvider';
+import {useUNSAFE_PortalContext} from './PortalProvider';
 
 export interface OverlayProps {
   /**
    * The container element in which the overlay portal will be placed.
    * @default document.body
+   * @deprecated - Use a parent UNSAFE_PortalProvider to set your portal container instead.
    */
   portalContainer?: Element,
   /** The overlay to render in the portal. */
@@ -55,8 +56,8 @@ export function Overlay(props: OverlayProps): ReactNode | null {
   let [contain, setContain] = useState(false);
   let contextValue = useMemo(() => ({contain, setContain}), [contain, setContain]);
 
-  let {getContainer} = useUNSTABLE_PortalContext();
-  if  (!props.portalContainer && getContainer) {
+  let {getContainer} = useUNSAFE_PortalContext();
+  if (!props.portalContainer && getContainer) {
     portalContainer = getContainer();
   }
 

packages/@react-aria/overlays/src/PortalProvider.tsx

@@ -13,22 +13,29 @@
 import React, {createContext, ReactNode, useContext} from 'react';
 
 export interface PortalProviderProps {
-  /* Should return the element where we should portal to. Can clear the context by passing null. */
-  getContainer?: () => HTMLElement | null
+  /** Should return the element where we should portal to. Can clear the context by passing null. */
+  getContainer?: () => HTMLElement | null,
+  /** The content of the PortalProvider. Should contain all children that want to portal their overlays to the element returned by the provided `getContainer()`. */
+  children: ReactNode
 }
 
-export const PortalContext = createContext<PortalProviderProps>({});
+export interface PortalProviderContextValue extends Omit<PortalProviderProps, 'children'>{};
 
-export function UNSTABLE_PortalProvider(props: PortalProviderProps & {children: ReactNode}): ReactNode {
+export const PortalContext = createContext<PortalProviderContextValue>({});
+
+/**
+ * Sets the portal container for all overlay elements rendered by its children.
+ */
+export function UNSAFE_PortalProvider(props: PortalProviderProps): ReactNode {
   let {getContainer} = props;
-  let {getContainer: ctxGetContainer} = useUNSTABLE_PortalContext();
+  let {getContainer: ctxGetContainer} = useUNSAFE_PortalContext();
   return (
     <PortalContext.Provider value={{getContainer: getContainer === null ? undefined : getContainer ?? ctxGetContainer}}>
       {props.children}
     </PortalContext.Provider>
   );
 }
 
-export function useUNSTABLE_PortalContext(): PortalProviderProps {
+export function useUNSAFE_PortalContext(): PortalProviderContextValue {
   return useContext(PortalContext) ?? {};
 }

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

@@ -19,7 +19,7 @@ export {ariaHideOutside} from './ariaHideOutside';
 export {usePopover} from './usePopover';
 export {useModalOverlay} from './useModalOverlay';
 export {Overlay, useOverlayFocusContain} from './Overlay';
-export {UNSTABLE_PortalProvider, useUNSTABLE_PortalContext} from './PortalProvider';
+export {UNSAFE_PortalProvider, useUNSAFE_PortalContext} from './PortalProvider';
 
 export type {AriaPositionProps, PositionAria} from './useOverlayPosition';
 export type {AriaOverlayProps, OverlayAria} from './useOverlay';
@@ -30,3 +30,4 @@ export type {AriaPopoverProps, PopoverAria} from './usePopover';
 export type {AriaModalOverlayProps, ModalOverlayAria} from './useModalOverlay';
 export type {OverlayProps} from './Overlay';
 export type {Placement, PlacementAxis, PositionProps} from '@react-types/overlays';
+export type {PortalProviderProps, PortalProviderContextValue} from './PortalProvider';

packages/@react-aria/overlays/src/useModal.tsx

@@ -14,6 +14,7 @@ import {DOMAttributes} from '@react-types/shared';
 import React, {AriaAttributes, ReactNode, useContext, useEffect, useMemo, useState} from 'react';
 import ReactDOM from 'react-dom';
 import {useIsSSR} from '@react-aria/ssr';
+import {useUNSAFE_PortalContext} from './PortalProvider';
 
 export interface ModalProviderProps extends DOMAttributes {
   children: ReactNode
@@ -112,6 +113,7 @@ export interface OverlayContainerProps extends ModalProviderProps {
   /**
    * The container element in which the overlay portal will be placed.
    * @default document.body
+   * @deprecated - Use a parent UNSAFE_PortalProvider to set your portal container instead.
    */
   portalContainer?: Element
 }
@@ -126,6 +128,10 @@ export interface OverlayContainerProps extends ModalProviderProps {
 export function OverlayContainer(props: OverlayContainerProps): React.ReactPortal | null {
   let isSSR = useIsSSR();
   let {portalContainer = isSSR ? null : document.body, ...rest} = props;
+  let {getContainer} = useUNSAFE_PortalContext();
+  if (!props.portalContainer && getContainer) {
+    portalContainer = getContainer();
+  }
 
   React.useEffect(() => {
     if (portalContainer?.closest('[data-overlay-container]')) {