feat(tearsheet): implement enablePresence feature

Author: makafsal

package.json

@@ -70,7 +70,7 @@
     "@carbon/grid": "^11.45.0",
     "@carbon/layout": "^11.43.0",
     "@carbon/motion": "^11.37.0",
-    "@carbon/react": "^1.95.0",
+    "@carbon/react": "^1.97.0",
     "@carbon/themes": "^11.62.0",
     "@carbon/type": "^11.49.0",
     "@commitlint/cli": "^20.0.0",

packages/ibm-products/src/components/Tearsheet/Tearsheet.stories.jsx

@@ -140,6 +140,11 @@ export default {
     },
     label: { control: { type: 'text' } },
     title: { control: { type: 'text' } },
+    enablePresence: {
+      control: { type: 'boolean' },
+      description:
+        'Enable presence mode to remove DOM element after tearsheet exits (preserves animations)',
+    },
     influencer: { control: { disable: true } },
     onClose: { control: { disable: true } },
     navigation: { control: { disable: true } },

packages/ibm-products/src/components/Tearsheet/Tearsheet.tsx

@@ -75,6 +75,13 @@ export interface TearsheetProps extends PropsWithChildren {
    */
   description?: ReactNode;
 
+  /**
+   * Specify whether the Tearsheet should opt in to presence mode.
+   * When enabled, the Tearsheet will not mount until it is opened
+   * and will unmount when it's closed, preserving exit animations.
+   */
+  enablePresence?: boolean;
+
   /**
    * Enable a close icon ('x') in the header area of the tearsheet. By default,
    * (when this prop is omitted, or undefined or null) a tearsheet does not
@@ -293,6 +300,13 @@ Tearsheet.propTypes = {
    */
   description: PropTypes.node,
 
+  /**
+   * Specify whether the Tearsheet should opt in to presence mode.
+   * When enabled, the Tearsheet will not mount until it is opened
+   * and will unmount when it's closed, preserving exit animations.
+   */
+  enablePresence: PropTypes.bool,
+
   /**
    * Enable a close icon ('x') in the header area of the tearsheet. By default,
    * (when this prop is omitted, or undefined or null) a tearsheet does not

packages/ibm-products/src/components/Tearsheet/TearsheetPresence.tsx

@@ -0,0 +1,83 @@
+/**
+ * Copyright IBM Corp. 2020, 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React, {
+  type PropsWithChildren,
+  type ReactElement,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import { PresenceContext } from './hooks/usePresenceContext';
+
+interface TearsheetPresenceProps extends PropsWithChildren {
+  /**
+   * Specify whether the Tearsheet should opt in to presence mode.
+   */
+  open: boolean;
+
+  /**
+   * Internal property for backwards compatibility. Specify
+   * whether the Tearsheet should opt in to presence mode.
+   */
+  _autoEnablePresence?: boolean;
+
+  /**
+   * Internal property to predefine the presence context's id
+   * for exclusivity.
+   */
+  _presenceId?: string;
+}
+
+/**
+ * TearsheetPresence is a wrapper component that manages the presence
+ * of a Tearsheet in the DOM. When enabled, the Tearsheet will not mount
+ * until it is opened and will unmount when it's closed, while preserving
+ * exit animations.
+ */
+export const TearsheetPresence = ({
+  open,
+  _presenceId: presenceId,
+  _autoEnablePresence: autoEnablePresence = true,
+  children,
+}: TearsheetPresenceProps): ReactElement | null => {
+  const [isPresent, setIsPresent] = useState(open);
+  const hasAnimatedOut = useRef(false);
+
+  useEffect(() => {
+    if (open) {
+      setIsPresent(true);
+      hasAnimatedOut.current = false;
+    }
+  }, [open]);
+
+  // Listen for animation end to remove from DOM
+  useEffect(() => {
+    if (!open && isPresent && !hasAnimatedOut.current) {
+      const timer = setTimeout(() => {
+        hasAnimatedOut.current = true;
+        setIsPresent(false);
+      }, 500); // Match the tearsheet animation duration
+
+      return () => clearTimeout(timer);
+    }
+  }, [open, isPresent]);
+
+  if (!isPresent) {
+    return null;
+  }
+
+  const presenceContextValue = {
+    id: presenceId || `tearsheet-presence-${Date.now()}`,
+  };
+
+  return (
+    <PresenceContext.Provider value={presenceContextValue}>
+      {children}
+    </PresenceContext.Provider>
+  );
+};

packages/ibm-products/src/components/Tearsheet/TearsheetShell.tsx

@@ -10,13 +10,15 @@ import React, {
   useEffect,
   useState,
   useRef,
+  useMemo,
   ComponentProps,
   PropsWithChildren,
   ReactNode,
   ForwardedRef,
   RefObject,
 } from 'react';
 import { useResizeObserver } from '../../global/js/hooks/useResizeObserver';
+import { usePresenceContext } from './hooks/usePresenceContext';
 
 // Other standard imports.
 import PropTypes from 'prop-types';
@@ -61,6 +63,13 @@ interface TearsheetShellProps extends PropsWithChildren {
    */
   className?: string;
 
+  /**
+   * Specify whether the Tearsheet should opt in to presence mode.
+   * When enabled, the Tearsheet will not mount until it is opened
+   * and will unmount when it's closed, preserving exit animations.
+   */
+  enablePresence?: boolean;
+
   /**
    * The accessibility title for the close icon (if shown).
    *
@@ -263,6 +272,7 @@ export const TearsheetShell = React.forwardRef(
       closeIconDescription = 'Close',
       currentStep,
       description,
+      enablePresence,
       hasCloseIcon,
       hasError,
       headerActions,
@@ -302,6 +312,12 @@ export const TearsheetShell = React.forwardRef(
     const modalRefValue = modalRef.current;
     const wide = size === 'wide';
 
+    // Use presence context - it handles enablePresence internally
+    const { isPresent, shouldBeOpen, handleExitComplete } = usePresenceContext(
+      open || false,
+      enablePresence || false
+    );
+
     // Keep track of the stack depth and our position in it (1-based, 0=closed)
     const [depth, setDepth] = useState(0);
     const [position, setPosition] = useState(0);
@@ -356,6 +372,39 @@ export const TearsheetShell = React.forwardRef(
       }
     }, [claimFocus, hasError, modalRef]);
 
+    // Handle exit animation complete for enablePresence
+    useEffect(() => {
+      if (!enablePresence || !modalRef.current) {
+        return;
+      }
+
+      const handleTransitionEnd = (event: TransitionEvent) => {
+        // Only handle transform transitions on the container element
+        const containerElement = modalRef.current?.querySelector(
+          `.${bc}__container`
+        );
+        if (
+          event.target === containerElement &&
+          event.propertyName === 'transform'
+        ) {
+          handleExitComplete();
+        }
+      };
+
+      const element = modalRef.current;
+      element.addEventListener(
+        'transitionend',
+        handleTransitionEnd as EventListener
+      );
+
+      return () => {
+        element.removeEventListener(
+          'transitionend',
+          handleTransitionEnd as EventListener
+        );
+      };
+    }, [enablePresence, modalRef, handleExitComplete]);
+
     useEffect(() => {
       const notify = () =>
         stack.all.forEach((handler) => {
@@ -420,6 +469,10 @@ export const TearsheetShell = React.forwardRef(
     }, [modalRef, width]);
 
     if (position <= depth) {
+      // If enablePresence is true and component is not present, don't render
+      if (enablePresence && !isPresent) {
+        return null;
+      }
       // Include a modal header if and only if one or more of these is given.
       // We can't use a Wrap for the ModalHeader because ComposedModal requires
       // the direct child to be the ModalHeader instance.
@@ -463,7 +516,7 @@ export const TearsheetShell = React.forwardRef(
               [`${bc}__container--mixed-size-stacking`]:
                 !areAllSameSizeVariant(),
             })}
-            {...{ onClose, open, selectorPrimaryFocus }}
+            {...{ onClose, open: shouldBeOpen, selectorPrimaryFocus }}
             onKeyDown={keyDownListener}
             preventCloseOnClickOutside={!isPassive}
             ref={modalRef}
@@ -690,6 +743,13 @@ TearsheetShell.propTypes = {
    */
   description: PropTypes.node,
 
+  /**
+   * Specify whether the Tearsheet should opt in to presence mode.
+   * When enabled, the Tearsheet will not mount until it is opened
+   * and will unmount when it's closed, preserving exit animations.
+   */
+  enablePresence: PropTypes.bool,
+
   /**
    * Enable a close icon ('x') in the header area of the tearsheet. By default,
    * (when this prop is omitted, or undefined or null) a tearsheet does not

packages/ibm-products/src/components/Tearsheet/hooks/usePresenceContext.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright IBM Corp. 2020, 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useEffect,
+  useRef,
+} from 'react';
+
+export interface PresenceContextValue {
+  id: string;
+}
+
+export const PresenceContext = createContext<PresenceContextValue | null>(null);
+
+export function usePresenceContext(
+  open: boolean,
+  enablePresence: boolean = false
+) {
+  const context = useContext(PresenceContext);
+  const [exitState, setExitState] = useState<'active' | 'idle' | 'finished'>(
+    'finished' // Always start as finished
+  );
+  const [shouldBeOpen, setShouldBeOpen] = useState(open);
+  const isInitialMount = useRef(true);
+
+  // Handle shouldBeOpen state - runs when open or enablePresence changes
+  useEffect(() => {
+    if (!enablePresence) {
+      // When presence is disabled, immediately mirror open state
+      setShouldBeOpen(open);
+      return;
+    }
+
+    if (open) {
+      // On initial mount with open=true, delay shouldBeOpen to trigger animation
+      if (isInitialMount.current) {
+        isInitialMount.current = false;
+        const timer = setTimeout(() => {
+          setShouldBeOpen(true);
+        }, 10);
+        return () => clearTimeout(timer);
+      } else {
+        setShouldBeOpen(true);
+      }
+    } else {
+      isInitialMount.current = false;
+      setShouldBeOpen(false);
+    }
+  }, [open, enablePresence]);
+
+  // Handle exitState transitions - only when enablePresence is true
+  useEffect(() => {
+    if (!enablePresence) {
+      return;
+    }
+
+    if (open) {
+      setExitState('active');
+    } else if (exitState === 'active') {
+      setExitState('idle');
+    }
+  }, [open, enablePresence, exitState]);
+
+  const handleExitComplete = useCallback(() => {
+    if (!open) {
+      setExitState('finished');
+    }
+  }, [open]);
+
+  // Component is present when open OR when exit animation hasn't finished
+  // If enablePresence is false, always present
+  const isPresent = context
+    ? true
+    : !enablePresence || open || exitState !== 'finished';
+  const isExiting = enablePresence && !open && exitState === 'idle';
+
+  return {
+    isPresent,
+    isExiting,
+    shouldBeOpen,
+    handleExitComplete,
+  };
+}