fix: overlay layout shift when auto-focusing input

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

@@ -79,7 +79,12 @@ export {
   useLoadMoreSentinel as UNSTABLE_useLoadMoreSentinel
 } from 'react-aria/private/utils/useLoadMoreSentinel';
 export {inertValue} from 'react-aria/private/utils/inertValue';
-export {isCtrlKeyPressed, willOpenKeyboard} from 'react-aria/private/utils/keyboard';
+export {
+  isCtrlKeyPressed,
+  isKeyboardOpen,
+  isKeyboardVisible,
+  willOpenKeyboard
+} from 'react-aria/private/utils/keyboard';
 export {useEnterAnimation, useExitAnimation} from 'react-aria/private/utils/animation';
 export {isFocusable, isTabbable} from 'react-aria/private/utils/isFocusable';
 export {getNonce} from 'react-aria/private/utils/getNonce';

packages/@react-spectrum/s2/src/Modal.tsx

@@ -40,6 +40,8 @@ const modalOverlayStyles = style({
   isolation: 'isolate',
   backgroundColor: 'transparent-black-500',
   opacity: {
+    default: 0,
+    isOpen: 1,
     isEntering: 0,
     isExiting: 0
   },
@@ -148,6 +150,8 @@ export const Modal = forwardRef(function Modal(props: ModalProps, ref: DOMRef<HT
               },
               backgroundColor: '--s2-container-bg',
               opacity: {
+                default: 0,
+                isOpen: 1,
                 isEntering: 0,
                 isExiting: 0
               },

packages/@react-types/shared/src/events.d.ts

@@ -13,6 +13,20 @@
 import {FocusableElement} from './dom';
 import {FocusEvent, MouseEvent, KeyboardEvent as ReactKeyboardEvent, SyntheticEvent} from 'react';
 
+// Type helper to extract the target element type from an event
+export type EventTargetType<T> = T extends SyntheticEvent<infer E, any> ? E : EventTarget;
+
+// Type helper to extract the event map from a target
+export type EventMapType<T extends EventTarget> = T extends Window
+  ? WindowEventMap
+  : T extends Document
+    ? DocumentEventMap
+    : T extends Element
+      ? HTMLElementEventMap
+      : T extends VisualViewport
+        ? VisualViewportEventMap
+        : GlobalEventHandlersEventMap;
+
 // Event bubbling can be problematic in real-world applications, so the default for React Spectrum components
 // is not to propagate. This can be overridden by calling continuePropagation() on the event.
 export type BaseEvent<T extends SyntheticEvent> = T & {

packages/dev/docs/pages/react-aria/getting-started.mdx

@@ -193,6 +193,10 @@ This is a quick way to get started, but you can also create your own custom clas
     --origin: translateY(-8px);
   }
 
+  &:not([data-open]) {
+    opacity: 0;
+  }
+
   &[data-entering] {
     animation: slide 200ms;
   }

packages/dev/docs/pages/react-aria/home/ExampleApp.tsx

@@ -787,7 +787,7 @@ function PlantModal(props: ModalOverlayProps) {
       ${isEntering ? 'animate-in fade-in duration-200 ease-out' : ''}
       ${isExiting ? 'animate-out fade-out duration-200 ease-in' : ''}
     `}>
-      {({isEntering, isExiting}) => (
+      {({isEntering, isExiting, isOpen}) => (
         <>
           {/* Inner position: sticky div sized to the visual viewport
             height so the modal appears in view.
@@ -799,6 +799,7 @@ function PlantModal(props: ModalOverlayProps) {
               <div
                 data-react-aria-top-layer="true"
                 className={`absolute top-0 left-0 w-full h-(--visual-viewport-height) z-30 hidden sm:flex items-center justify-center pointer-events-none [filter:drop-shadow(0_0_3px_white)] dark:filter-none
+                ${!isOpen ? 'opacity-0' : ''}
                 ${isEntering ? 'animate-in zoom-in-105 ease-out duration-200' : ''}
                 ${isExiting ? 'animate-out zoom-out-95 ease-in duration-200' : ''}
               `}>

packages/react-aria-components/docs/Modal.mdx

@@ -111,6 +111,10 @@ import {DialogTrigger, Modal, Dialog, Button, Heading, TextField, Label, Input}
   width: max-content;
   max-width: 300px;
 
+  &:not([data-open]) {
+    opacity: 0;
+  }
+
   &[data-entering] {
     animation: modal-zoom 300ms cubic-bezier(0.175, 0.885, 0.32, 1.275);
   }

packages/react-aria-components/docs/Popover.mdx

@@ -100,6 +100,10 @@ import {DialogTrigger, Popover, Dialog, Button, OverlayArrow, Heading, Switch} f
     stroke-width: 1px;
   }
 
+  &:not([data-open]) {
+    opacity: 0;
+  }
+
   &[data-entering],
   &[data-exiting] {
     transform: var(--starting-scale) var(--origin);
@@ -447,6 +451,10 @@ Popovers also support entry and exit animations via states exposed as data attri
   transition: opacity 300ms, scale 300ms;
   transform-origin: var(--trigger-anchor-point);
 
+  &:not([data-open]) {
+    opacity: 0;
+  }
+
   &[data-entering],
   &[data-exiting] {
     opacity: 0;

packages/react-aria-components/docs/examples/command-palette.mdx

@@ -108,7 +108,8 @@ function CommandPaletteExample() {
         >
           <div className="sticky top-0 left-0 w-full h-(--visual-viewport-height) flex items-start sm:items-center justify-center p-4 box-border text-center">
             <Modal
-              className={({ isEntering, isExiting }) => `
+              className={({ isEntering, isExiting, isOpen }) => `
+              ${!isOpen ? 'opacity-0' : ''}
               ${isEntering ? 'animate-in zoom-in-95 ease-out duration-300' : ''}
               ${isExiting ? 'animate-out zoom-out-95 ease-in duration-200' : ''}
             `}

packages/react-aria-components/docs/examples/destructive-dialog.mdx

@@ -50,8 +50,9 @@ function ModalExample() {
           ${isEntering ? 'animate-in fade-in duration-300 ease-out' : ''}
           ${isExiting ? 'animate-out fade-out duration-200 ease-in' : ''}
         `}>
-          <Modal className={({isEntering, isExiting}) => `
+          <Modal className={({isEntering, isExiting, isOpen}) => `
             sticky top-0 left-0 w-full h-(--visual-viewport-height) flex items-center justify-center p-4 box-border text-center
+            ${!isOpen ? 'opacity-0' : ''}
             ${isEntering ? 'animate-in zoom-in-95 ease-out duration-300' : ''}
             ${isExiting ? 'animate-out zoom-out-95 ease-in duration-200' : ''}
           `}>

packages/react-aria-components/docs/styling.mdx

@@ -281,6 +281,10 @@ Overlay components such as [Popover](Popover.html) and [Modal](Modal.html) suppo
 .react-aria-Popover {
   transition: opacity 300ms;
 
+  &:not([data-open]) {
+    opacity: 0;
+  }
+
   &[data-entering],
   &[data-exiting] {
     opacity: 0;
@@ -295,6 +299,10 @@ Note that the `[data-entering]` state is only applied for one frame when using C
   /* entry transition */
   transition: transform 300ms, opacity 300ms;
 
+  &:not([data-open]) {
+    opacity: 0;
+  }
+
   /* starting state of the entry transition */
   &[data-entering] {
     opacity: 0;
@@ -315,6 +323,10 @@ Note that the `[data-entering]` state is only applied for one frame when using C
 For more complex animations, you can also apply CSS keyframe animations using the same `[data-entering]` and `[data-exiting]` states.
 
 ```css render=false
+.react-aria-Popover:not([data-open]) {
+  opacity: 0;
+}
+
 .react-aria-Popover[data-entering] {
   animation: slide 300ms;
 }

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

@@ -11,7 +11,6 @@
  */
 
 import {AriaModalOverlayProps, useModalOverlay} from 'react-aria/useModalOverlay';
-
 import {
   ClassNameOrFunction,
   ContextValue,
@@ -34,9 +33,19 @@ import {
   useOverlayTriggerState
 } from 'react-stately/useOverlayTriggerState';
 import {OverlayTriggerStateContext} from './Dialog';
-import React, {createContext, ForwardedRef, forwardRef, useContext, useMemo, useRef} from 'react';
+import React, {
+  createContext,
+  ForwardedRef,
+  forwardRef,
+  useContext,
+  useMemo,
+  useRef,
+  useState
+} from 'react';
+import {runAfterKeyboard} from 'react-aria/private/utils/runAfterKeyboard';
 import {useEnterAnimation, useExitAnimation} from 'react-aria/private/utils/animation';
 import {useIsSSR} from 'react-aria/SSRProvider';
+import {useLayoutEffect} from 'react-aria/private/utils/useLayoutEffect';
 import {useObjectRef} from 'react-aria/useObjectRef';
 import {useViewportSize} from 'react-aria/private/utils/useViewportSize';
 
@@ -75,6 +84,7 @@ export interface ModalOverlayProps
 interface InternalModalContextValue {
   modalProps: DOMAttributes;
   modalRef: RefObject<HTMLDivElement | null>;
+  isOpen: boolean;
   isExiting: boolean;
   isDismissable?: boolean;
 }
@@ -83,6 +93,12 @@ export const ModalContext = createContext<ContextValue<ModalOverlayProps, HTMLDi
 const InternalModalContext = createContext<InternalModalContextValue | null>(null);
 
 export interface ModalRenderProps {
+  /**
+   * Whether the modal is ready to be displayed. Use this to avoid layout shift.
+   *
+   * @selector [data-open]
+   */
+  isOpen: boolean;
   /**
    * Whether the modal is currently entering. Use this to apply animations.
    *
@@ -229,11 +245,13 @@ function ModalOverlayInner({UNSTABLE_portalContainer, ...props}: ModalOverlayInn
   let {state} = props;
   let {modalProps, underlayProps} = useModalOverlay(props, state, modalRef);
 
-  let entering = useEnterAnimation(props.overlayRef) || props.isEntering || false;
+  let [isOpen, setIsOpen] = useState(false);
+  let entering = useEnterAnimation(props.overlayRef, isOpen) || props.isEntering || false;
   let renderProps = useRenderProps({
     ...props,
     defaultClassName: 'react-aria-ModalOverlay',
     values: {
+      isOpen,
       isEntering: entering,
       isExiting: props.isExiting,
       state
@@ -262,6 +280,10 @@ function ModalOverlayInner({UNSTABLE_portalContainer, ...props}: ModalOverlayInn
     '--page-height': pageHeight !== undefined ? pageHeight + 'px' : undefined
   };
 
+  // Since an auto-focused input may open the OSK, we defer the reveal, as a courtesy, to avoid layout shift.
+  // TODO: This can cause native focus scroll-into-view to abort, so we might want to do that manually?
+  useLayoutEffect(() => runAfterKeyboard(() => setIsOpen(true)), []);
+
   // oxlint-disable react/react-compiler
   return (
     <Overlay isExiting={props.isExiting} portalContainer={UNSTABLE_portalContainer}>
@@ -270,13 +292,20 @@ function ModalOverlayInner({UNSTABLE_portalContainer, ...props}: ModalOverlayInn
         {...renderProps}
         style={style}
         ref={props.overlayRef}
+        data-open={isOpen || undefined}
         data-entering={entering || undefined}
         data-exiting={props.isExiting || undefined}>
         <Provider
           values={[
             [
               InternalModalContext,
-              {modalProps, modalRef, isExiting: props.isExiting, isDismissable: props.isDismissable}
+              {
+                modalProps,
+                modalRef,
+                isExiting: props.isExiting,
+                isOpen,
+                isDismissable: props.isDismissable
+              }
             ],
             [OverlayTriggerStateContext, state]
           ]}>
@@ -301,16 +330,17 @@ interface ModalContentProps
 }
 
 function ModalContent(props: ModalContentProps) {
-  let {modalProps, modalRef, isExiting, isDismissable} = useContext(InternalModalContext)!;
+  let {modalProps, modalRef, isExiting, isOpen, isDismissable} = useContext(InternalModalContext)!;
   let state = useContext(OverlayTriggerStateContext)!;
   let mergedRefs = useMemo(() => mergeRefs(props.modalRef, modalRef), [props.modalRef, modalRef]);
 
   let ref = useObjectRef(mergedRefs);
-  let entering = useEnterAnimation(ref);
+  let entering = useEnterAnimation(ref, isOpen);
   let renderProps = useRenderProps({
     ...props,
     defaultClassName: 'react-aria-Modal',
     values: {
+      isOpen,
       isEntering: entering,
       isExiting,
       state
@@ -322,6 +352,7 @@ function ModalContent(props: ModalContentProps) {
       {...mergeProps(filterDOMProps(props, {global: true}), modalProps)}
       {...renderProps}
       ref={ref}
+      data-open={isOpen || undefined}
       data-entering={entering || undefined}
       data-exiting={isExiting || undefined}>
       {isDismissable && <DismissButton onDismiss={state.close} />}

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

@@ -52,6 +52,7 @@ import React, {
   useRef,
   useState
 } from 'react';
+import {runAfterKeyboard} from 'react-aria/private/utils/runAfterKeyboard';
 import {useEnterAnimation, useExitAnimation} from 'react-aria/private/utils/animation';
 import {useIsHidden} from 'react-aria/private/collections/Hidden';
 import {useLayoutEffect} from 'react-aria/private/utils/useLayoutEffect';
@@ -125,6 +126,12 @@ export interface PopoverRenderProps {
    * @selector [data-placement="left | right | top | bottom"]
    */
   placement: PlacementAxis | null;
+  /**
+   * Whether the popover is ready to be displayed. Use this to avoid layout shift.
+   *
+   * @selector [data-open]
+   */
+  isOpen: boolean;
   /**
    * Whether the popover is currently entering. Use this to apply animations.
    *
@@ -173,6 +180,7 @@ export const Popover = /*#__PURE__*/ (forwardRef as forwardRefType)(function Pop
       children = children({
         trigger: props.trigger || null,
         placement: 'bottom',
+        isOpen: false,
         isEntering: false,
         isExiting: false,
         defaultChildren: null
@@ -223,6 +231,9 @@ function PopoverInner({
   let groupCtx = useContext(PopoverGroupContext);
   let isSubPopover = groupCtx && props.trigger === 'SubmenuTrigger';
 
+  let [isOpen, setIsOpen] = useState(false);
+  let [isDialog, setIsDialog] = useState(false);
+
   let {popoverProps, underlayProps, arrowProps, placement, triggerAnchorPoint} = usePopover(
     {
       ...props,
@@ -237,7 +248,7 @@ function PopoverInner({
 
   let ref = props.popoverRef as RefObject<HTMLDivElement | null>;
   // oxlint-disable-next-line react/react-compiler
-  let isEntering = useEnterAnimation(ref, !!placement) || props.isEntering || false;
+  let isEntering = useEnterAnimation(ref, !!placement && isOpen) || props.isEntering || false;
   // oxlint-disable-next-line react/react-compiler
   let renderProps = useRenderProps({
     // oxlint-disable-next-line react/react-compiler
@@ -248,6 +259,7 @@ function PopoverInner({
       // oxlint-disable-next-line react/react-compiler
       trigger: props.trigger || null,
       placement,
+      isOpen: !!placement && isOpen,
       // oxlint-disable-next-line react/react-compiler
       isEntering,
       isExiting
@@ -258,10 +270,9 @@ function PopoverInner({
   // or a dialog is already nested inside the popover.
   // oxlint-disable-next-line react/react-compiler
   let shouldBeDialog = !props.isNonModal || props.trigger === 'SubmenuTrigger';
-  let [isDialog, setDialog] = useState(false);
   useLayoutEffect(() => {
     if (ref.current) {
-      setDialog(shouldBeDialog && !ref.current.querySelector('[role=dialog]'));
+      setIsDialog(shouldBeDialog && !ref.current.querySelector('[role=dialog]'));
     }
   }, [ref, shouldBeDialog]);
 
@@ -315,6 +326,10 @@ function PopoverInner({
     '--trigger-width': renderProps.style?.['--trigger-width'] || triggerWidth
   };
 
+  // Since an auto-focused input may open the OSK, we defer the reveal, as a courtesy, to avoid layout shift.
+  // TODO: This can cause native focus scroll-into-view to abort, so we might want to do that manually?
+  useLayoutEffect(() => runAfterKeyboard(() => setIsOpen(true)), []);
+
   // oxlint-disable react/react-compiler
   let overlay = (
     <dom.div
@@ -331,6 +346,7 @@ function PopoverInner({
       dir={props.dir}
       data-trigger={props.trigger}
       data-placement={placement}
+      data-open={(!!placement && isOpen) || undefined}
       data-entering={isEntering || undefined}
       data-exiting={isExiting || undefined}>
       {/* oxlint-disable-next-line react/react-compiler */}

packages/react-aria/exports/private/utils/keyboard.ts

@@ -1 +1,6 @@
-export {isCtrlKeyPressed, willOpenKeyboard} from '../../../src/utils/keyboard';
+export {
+  isCtrlKeyPressed,
+  isKeyboardOpen,
+  isKeyboardVisible,
+  willOpenKeyboard
+} from '../../../src/utils/keyboard';

packages/react-aria/exports/private/utils/runAfterKeyboard.ts

@@ -0,0 +1 @@
+export {runAfterKeyboard, runAfterKeyboardTransition} from '../../../src/utils/runAfterKeyboard';