Add isEntering and isExiting props to control animation from outside (#5358)

Author: devongovett

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

@@ -120,7 +120,7 @@ export function useOverlay(props: AriaOverlayProps, ref: RefObject<Element>): Ov
   };
 
   // Handle clicking outside the overlay to close it
-  useInteractOutside({ref, onInteractOutside: isDismissable ? onInteractOutside : null, onInteractOutsideStart});
+  useInteractOutside({ref, onInteractOutside: isDismissable && isOpen ? onInteractOutside : null, onInteractOutsideStart});
 
   let {focusWithinProps} = useFocusWithin({
     isDisabled: !shouldCloseOnBlur,

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

@@ -288,46 +288,61 @@ This enables using props like [animate](https://www.framer.com/motion/animation/
 ```tsx
 <MotionModal
   initial={{opacity: 0}}
-  animate={{opacity: 1}}
-  exit={{opacity: 0}}>
+  animate={{opacity: 1}}>
   {/* ... */}
 </MotionModal>
 ```
 
-Entry and exit animations can also be done with the [AnimatePresence](https://www.framer.com/motion/animate-presence/) component. Maintain your own `isOpen` state, and use this to control whether the child of `AnimatePresence` is rendered. Then, force the React Aria overlay component to always mount by setting the `isOpen` prop to true. This way, it won't unmount until the animation is complete.
+Overlay exit animations can be implemented using the `isExiting` prop, which keeps the element in the DOM until an animation is complete. Framer Motion's [variants](https://www.framer.com/motion/animation/#variants) are a good way to setup named animation states.
 
 ```tsx
-import {AnimatePresence} from 'framer-motion';
+type AnimationState = 'unmounted' | 'hidden' | 'visible';
 
 function Example() {
-  let [isOpen, setOpen] = React.useState(false);
+  /*- begin highlight -*/
+  // Track animation state.
+  let [animation, setAnimation] = React.useState<AnimationState>('unmounted');
+  /*- end highlight -*/
 
   return (
-    <AnimatePresence>
-      {isOpen &&
-        <MotionModalOverlay
-          // Force mount so that AnimatePresence works.
-          /*- begin highlight -*/
-          isOpen
-          /*- end highlight -*/
-          onOpenChange={setOpen}
-          initial={{opacity: 0}}
-          animate={{opacity: 1}}
-          exit={{opacity: 0}}>
-          <MotionModal
-            initial={{opacity: 0, y: 32}}
-            animate={{opacity: 1, y: 0}}
-            exit={{opacity: 0, y: 32}}>
-            {/* ... */}
-          </MotionModal>
-        </MotionModalOverlay>
-      }
-    </AnimatePresence>
+    <DialogTrigger
+      /*- begin highlight -*/
+      // Start animation when open state changes.
+      onOpenChange={isOpen => setAnimation(isOpen ? 'visible' : 'hidden')}
+      /*- end highlight -*/
+    >
+      <Button>Open dialog</Button>
+      <MotionModalOverlay
+        /*- begin highlight -*/
+        // Prevent modal from unmounting during animation.
+        isExiting={animation === 'hidden'}
+        // Reset animation state once it is complete.
+        onAnimationComplete={animation => {
+          setAnimation(a => animation === 'hidden' && a === 'hidden' ? 'unmounted' : a)
+        }}
+        /*- end highlight -*/
+        variants={{
+          hidden: {opacity: 0},
+          visible: {opacity: 1}
+        }}
+        initial="hidden"
+        animate={animation}>
+        <MotionModal
+          variants={{
+            hidden: {opacity: 0, y: 32},
+            visible: {opacity: 1, y: 0}
+          }}>
+          {/* ... */}
+        </MotionModal>
+      </MotionModalOverlay>
+    </DialogTrigger>
   );
 }
 ```
 
-`AnimatePresence` also allows you to animate when items are added or removed in collection components. Use `array.map` to create children, and make sure each child has a unique `key` in addition to an `id` to ensure Framer Motion can track it.
+**Note**: Framer Motion's `AnimatePresence` component may not work with React Aria overlays in all cases, so the example shown above is the recommended approach for exit animations.
+
+The [AnimatePresence](https://www.framer.com/motion/animate-presence/) component allows you to animate when items are added or removed in collection components. Use `array.map` to create children, and make sure each child has a unique `key` in addition to an `id` to ensure Framer Motion can track it.
 
 ```tsx
 import {GridList, GridListItem} from 'react-aria-components';

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

@@ -18,7 +18,16 @@ import {OverlayTriggerProps, OverlayTriggerState, useOverlayTriggerState} from '
 import {OverlayTriggerStateContext} from './Dialog';
 import React, {createContext, ForwardedRef, forwardRef, RefObject, useContext, useMemo, useRef} from 'react';
 
-export interface ModalOverlayProps extends AriaModalOverlayProps, OverlayTriggerProps, RenderProps<ModalRenderProps>, SlotProps {}
+export interface ModalOverlayProps extends AriaModalOverlayProps, OverlayTriggerProps, RenderProps<ModalRenderProps>, SlotProps {
+  /**
+   * Whether the modal is currently performing an entry animation.
+   */
+  isEntering?: boolean,
+  /**
+   * Whether the modal is currently performing an exit animation.
+   */
+  isExiting?: boolean
+}
 
 interface InternalModalContextValue {
   modalProps: DOMAttributes,
@@ -61,6 +70,8 @@ function Modal(props: ModalOverlayProps, ref: ForwardedRef<HTMLDivElement>) {
     defaultOpen,
     onOpenChange,
     children,
+    isEntering,
+    isExiting,
     ...otherProps
   } = props;
 
@@ -70,7 +81,9 @@ function Modal(props: ModalOverlayProps, ref: ForwardedRef<HTMLDivElement>) {
       isKeyboardDismissDisabled={isKeyboardDismissDisabled}
       isOpen={isOpen}
       defaultOpen={defaultOpen}
-      onOpenChange={onOpenChange}>
+      onOpenChange={onOpenChange}
+      isEntering={isEntering}
+      isExiting={isExiting}>
       <ModalContent {...otherProps} modalRef={ref}>
         {children}
       </ModalContent>
@@ -101,7 +114,7 @@ function ModalOverlayWithForwardRef(props: ModalOverlayProps, ref: ForwardedRef<
   let modalRef = useRef<HTMLDivElement>(null);
   let isOverlayExiting = useExitAnimation(objectRef, state.isOpen);
   let isModalExiting = useExitAnimation(modalRef, state.isOpen);
-  let isExiting = isOverlayExiting || isModalExiting;
+  let isExiting = isOverlayExiting || isModalExiting || props.isExiting || false;
   let isSSR = useIsSSR();
 
   if ((!state.isOpen && !isExiting) || isSSR) {
@@ -128,7 +141,7 @@ function ModalOverlayInner(props: ModalOverlayInnerProps) {
   let {state} = props;
   let {modalProps, underlayProps} = useModalOverlay(props, state, modalRef);
 
-  let entering = useEnterAnimation(props.overlayRef);
+  let entering = useEnterAnimation(props.overlayRef) || props.isEntering || false;
   let renderProps = useRenderProps({
     ...props,
     defaultClassName: 'react-aria-ModalOverlay',

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

@@ -25,7 +25,15 @@ export interface PopoverProps extends Omit<PositionProps, 'isOpen'>, Omit<AriaPo
    * When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc.,
    * this is set automatically. It is only required when used standalone.
    */
-  triggerRef?: RefObject<Element>
+  triggerRef?: RefObject<Element>,
+  /**
+   * Whether the popover is currently performing an entry animation.
+   */
+  isEntering?: boolean,
+  /**
+   * Whether the popover is currently performing an exit animation.
+   */
+  isExiting?: boolean
 }
 
 export interface PopoverRenderProps {
@@ -53,7 +61,7 @@ function Popover(props: PopoverProps, ref: ForwardedRef<HTMLElement>) {
   let contextState = useContext(OverlayTriggerStateContext);
   let localState = useOverlayTriggerState(props);
   let state = props.isOpen != null || props.defaultOpen != null || !contextState ? localState : contextState;
-  let isExiting = useExitAnimation(ref, state.isOpen);
+  let isExiting = useExitAnimation(ref, state.isOpen) || props.isExiting || false;
   let isHidden = useContext(HiddenContext);
 
   // If we are in a hidden tree, we still need to preserve our children.
@@ -92,6 +100,7 @@ export {_Popover as Popover};
 
 interface PopoverInnerProps extends AriaPopoverProps, RenderProps<PopoverRenderProps>, SlotProps {
   state: OverlayTriggerState,
+  isEntering?: boolean,
   isExiting: boolean
 }
 
@@ -102,7 +111,7 @@ function PopoverInner({state, isExiting, ...props}: PopoverInnerProps) {
   }, state);
 
   let ref = props.popoverRef as RefObject<HTMLDivElement>;
-  let isEntering = useEnterAnimation(ref, !!placement);
+  let isEntering = useEnterAnimation(ref, !!placement) || props.isEntering || false;
   let renderProps = useRenderProps({
     ...props,
     defaultClassName: 'react-aria-Popover',
@@ -117,7 +126,7 @@ function PopoverInner({state, isExiting, ...props}: PopoverInnerProps) {
 
   return (
     <Overlay isExiting={isExiting}>
-      {!props.isNonModal && <div {...underlayProps} style={{position: 'fixed', inset: 0}} />}
+      {!props.isNonModal && state.isOpen && <div {...underlayProps} style={{position: 'fixed', inset: 0}} />}
       <div
         {...mergeProps(filterDOMProps(props as any), popoverProps)}
         {...renderProps}

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

@@ -28,7 +28,15 @@ export interface TooltipProps extends PositionProps, OverlayTriggerProps, AriaLa
    *
    * When used within a TooltipTrigger this is set automatically. It is only required when used standalone.
    */
-  triggerRef?: RefObject<Element>
+  triggerRef?: RefObject<Element>,
+  /**
+   * Whether the tooltip is currently performing an entry animation.
+   */
+  isEntering?: boolean,
+  /**
+   * Whether the tooltip is currently performing an exit animation.
+   */
+  isExiting?: boolean
 }
 
 export interface TooltipRenderProps {
@@ -84,7 +92,7 @@ function Tooltip(props: TooltipProps, ref: ForwardedRef<HTMLDivElement>) {
   let contextState = useContext(TooltipTriggerStateContext);
   let localState = useTooltipTriggerState(props);
   let state = props.isOpen != null || props.defaultOpen != null || !contextState ? localState : contextState;
-  let isExiting = useExitAnimation(ref, state.isOpen);
+  let isExiting = useExitAnimation(ref, state.isOpen) || props.isExiting || false;
   if (!state.isOpen && !isExiting) {
     return null;
   }
@@ -114,7 +122,7 @@ function TooltipInner(props: TooltipProps & {isExiting: boolean, tooltipRef: Ref
     isOpen: state.isOpen
   });
 
-  let isEntering = useEnterAnimation(props.tooltipRef, !!placement);
+  let isEntering = useEnterAnimation(props.tooltipRef, !!placement) || props.isEntering || false;
   let renderProps = useRenderProps({
     ...props,
     defaultClassName: 'react-aria-Tooltip',

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

@@ -175,6 +175,19 @@ export function useContextProps<T, U extends SlotProps, E extends Element>(props
   let mergedRef = useObjectRef(useMemo(() => mergeRefs(ref, contextRef), [ref, contextRef]));
   let mergedProps = mergeProps(contextProps, props) as unknown as T;
 
+  // mergeProps does not merge `style`. Adding this there might be a breaking change.
+  if (
+    'style' in contextProps &&
+    contextProps.style &&
+    typeof contextProps.style === 'object' &&
+    'style' in props &&
+    props.style &&
+    typeof props.style === 'object'
+  ) {
+    // @ts-ignore
+    mergedProps.style = {...contextProps.style, ...props.style};
+  }
+
   // A parent component might need the props from a child, so call slot callback if needed.
   useEffect(() => {
     if (callback) {
@@ -257,7 +270,7 @@ function useAnimation(ref: RefObject<HTMLElement>, isActive: boolean, onEnd: ()
     if (isActive && ref.current) {
       // Make sure there's actually an animation, and it wasn't there before we triggered the update.
       let computedStyle = window.getComputedStyle(ref.current);
-      if (computedStyle.animationName !== 'none' && computedStyle.animation !== prevAnimation.current) {
+      if (computedStyle.animationName && computedStyle.animationName !== 'none' && computedStyle.animation !== prevAnimation.current) {
         let onAnimationEnd = (e: AnimationEvent) => {
           if (e.target === ref.current) {
             element.removeEventListener('animationend', onAnimationEnd);

packages/react-aria-components/test/Dialog.test.js

@@ -246,4 +246,37 @@ describe('Dialog', () => {
     expect(onOpenChange).toHaveBeenCalledTimes(1);
     expect(onOpenChange).toHaveBeenCalledWith(false);
   });
+
+  it('supports isEntering and isExiting props', async () => {
+    function TestModal(props) {
+      return (
+        <DialogTrigger>
+          <Button />
+          <Modal {...props}>
+            <Dialog aria-label="Modal">A modal</Dialog>
+          </Modal>
+        </DialogTrigger>
+      );
+    }
+
+    let {getByRole, rerender} = render(<TestModal isEntering />);
+
+    let button = getByRole('button');
+    await user.click(button);
+
+    let modal = getByRole('dialog').closest('.react-aria-ModalOverlay');
+    expect(modal).toHaveAttribute('data-entering');
+
+    rerender(<TestModal />);
+    expect(modal).not.toHaveAttribute('data-entering');
+
+    rerender(<TestModal isExiting />);
+    await user.click(button);
+
+    expect(modal).toBeInTheDocument();
+    expect(modal).toHaveAttribute('data-exiting');
+
+    rerender(<TestModal />);
+    expect(modal).not.toBeInTheDocument();
+  });
 });

packages/react-aria-components/test/Popover.test.js

@@ -15,10 +15,10 @@ import {Button, Dialog, DialogTrigger, OverlayArrow, Popover} from '../';
 import React from 'react';
 import userEvent from '@testing-library/user-event';
 
-let TestPopover = () => (
+let TestPopover = (props) => (
   <DialogTrigger>
     <Button />
-    <Popover>
+    <Popover {...props}>
       <OverlayArrow>
         <svg width={12} height={12}>
           <path d="M0 0,L6 6,L12 0" />
@@ -128,4 +128,26 @@ describe('Popover', () => {
     expect(onOpenChange).toHaveBeenCalledTimes(1);
     expect(onOpenChange).toHaveBeenCalledWith(false);
   });
+
+  it('supports isEntering and isExiting props', async () => {
+    let {getByRole, rerender} = render(<TestPopover isEntering />);
+
+    let button = getByRole('button');
+    await user.click(button);
+
+    let popover = getByRole('dialog').closest('.react-aria-Popover');
+    expect(popover).toHaveAttribute('data-entering');
+
+    rerender(<TestPopover />);
+    expect(popover).not.toHaveAttribute('data-entering');
+
+    rerender(<TestPopover isExiting />);
+    await user.click(button);
+
+    expect(popover).toBeInTheDocument();
+    expect(popover).toHaveAttribute('data-exiting');
+
+    rerender(<TestPopover />);
+    expect(popover).not.toBeInTheDocument();
+  });
 });