From aebfe7932293e316983c1c460338966a271a65b5 Mon Sep 17 00:00:00 2001
From: wangdicoder <wangdicoder@gmail.com>
Date: Sat, 21 Mar 2026 21:21:30 +1100
Subject: [PATCH 1/3] feat: refactor Transaction component

---
 packages/react/package.json                   |   2 -
 .../__snapshots__/alert.test.tsx.snap         |   2 +-
 packages/react/src/drawer/drawer.tsx          |   7 +-
 .../__snapshots__/message.test.tsx.snap       |   2 +-
 packages/react/src/message/message.tsx        |   6 +-
 packages/react/src/modal/modal.tsx            |   7 +-
 packages/react/src/overlay/overlay.tsx        |   6 +-
 .../__snapshots__/transition.test.tsx.snap    |   2 +-
 packages/react/src/transition/index.tsx       |   2 +
 packages/react/src/transition/transition.tsx  | 103 +++++++--
 .../react/src/transition/use-transition.ts    | 217 ++++++++++++++++++
 pnpm-lock.yaml                                |  38 ---
 12 files changed, 322 insertions(+), 72 deletions(-)
 create mode 100644 packages/react/src/transition/use-transition.ts

diff --git a/packages/react/package.json b/packages/react/package.json
index 97469401..e345e219 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -66,7 +66,6 @@
     "@tiny-design/icons": "workspace:*",
     "@tiny-design/tokens": "workspace:*",
     "classnames": "^2.3.1",
-    "react-transition-group": "^4.4.2",
     "tslib": "^2.3.1"
   },
   "devDependencies": {
@@ -75,7 +74,6 @@
     "@types/jest": "^29.0.0",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
-    "@types/react-transition-group": "^4.4.4",
     "jest": "^29.0.0",
     "jest-environment-jsdom": "^29.0.0",
     "autoprefixer": "^10.4.4",
diff --git a/packages/react/src/alert/__tests__/__snapshots__/alert.test.tsx.snap b/packages/react/src/alert/__tests__/__snapshots__/alert.test.tsx.snap
index c85f2694..f8216353 100644
--- a/packages/react/src/alert/__tests__/__snapshots__/alert.test.tsx.snap
+++ b/packages/react/src/alert/__tests__/__snapshots__/alert.test.tsx.snap
@@ -3,7 +3,7 @@
 exports[`<Alert /> should match the snapshot 1`] = `
 <DocumentFragment>
   <div
-    class="ty-alert ty-alert_info ty-undefined-appear ty-undefined-appear-active"
+    class="ty-alert ty-alert_info ty-undefined-enter"
     role="alert"
   >
     <div>
diff --git a/packages/react/src/drawer/drawer.tsx b/packages/react/src/drawer/drawer.tsx
index 52c88c5b..a57acbc5 100755
--- a/packages/react/src/drawer/drawer.tsx
+++ b/packages/react/src/drawer/drawer.tsx
@@ -1,6 +1,6 @@
 import React, { useContext, useEffect, useId, useRef, useState } from 'react';
 import classNames from 'classnames';
-import { CSSTransition } from 'react-transition-group';
+import Transition from '../transition';
 import Overlay from '../overlay';
 import { ConfigContext } from '../config-provider/config-context';
 import { getPrefixCls } from '../_utils/general';
@@ -91,11 +91,12 @@ const Drawer = React.forwardRef<HTMLDivElement, DrawerProps>((props, ref) => {
       }}
       style={maskStyle}>
       <div ref={ref} className={cls} style={{ ...style, ...sty }}>
-        <CSSTransition
+        <Transition
           appear={true}
           nodeRef={nodeRef}
           in={drawerVisible}
           timeout={0}
+          unmountOnExit={false}
           classNames={`${prefixCls}__content_move`}>
           <div
             ref={nodeRef}
@@ -113,7 +114,7 @@ const Drawer = React.forwardRef<HTMLDivElement, DrawerProps>((props, ref) => {
             <div className={`${prefixCls}__body`}>{children}</div>
             {footer && <div className={`${prefixCls}__footer`}>{footer}</div>}
           </div>
-        </CSSTransition>
+        </Transition>
       </div>
     </Overlay>
   );
diff --git a/packages/react/src/message/__tests__/__snapshots__/message.test.tsx.snap b/packages/react/src/message/__tests__/__snapshots__/message.test.tsx.snap
index ae3da2a5..3bbcad69 100644
--- a/packages/react/src/message/__tests__/__snapshots__/message.test.tsx.snap
+++ b/packages/react/src/message/__tests__/__snapshots__/message.test.tsx.snap
@@ -3,7 +3,7 @@
 exports[`<Message /> should match the snapshot 1`] = `
 <DocumentFragment>
   <div
-    class="ty-message ty-message_fade-slide-appear ty-message_fade-slide-appear-active"
+    class="ty-message ty-message_fade-slide-enter"
     role="alert"
   >
     <svg
diff --git a/packages/react/src/message/message.tsx b/packages/react/src/message/message.tsx
index 5f926402..737cd9ee 100755
--- a/packages/react/src/message/message.tsx
+++ b/packages/react/src/message/message.tsx
@@ -1,6 +1,6 @@
 import React, { useEffect, useRef, useState, useContext } from 'react';
 import classNames from 'classnames';
-import { CSSTransition } from 'react-transition-group';
+import Transition from '../transition';
 import { ConfigContext } from '../config-provider/config-context';
 import { getPrefixCls } from '../_utils/general';
 import {
@@ -72,13 +72,13 @@ const Message = (props: MessageProps): JSX.Element => {
   }, [duration, willUnmount]);
 
   return (
-    <CSSTransition nodeRef={ref} in={visible} appear={true} timeout={0} classNames={`${prefixCls}_fade-slide`}>
+    <Transition nodeRef={ref} in={visible} appear={true} timeout={0} unmountOnExit={false} classNames={`${prefixCls}_fade-slide`}>
       <div role="alert" className={cls} style={style} ref={ref}>
         {renderIcon()}
         <span className={`${prefixCls}__content`}>{content}</span>
         {extra && <div className={`${prefixCls}__extra`}>{extra}</div>}
       </div>
-    </CSSTransition>
+    </Transition>
   );
 };
 
diff --git a/packages/react/src/modal/modal.tsx b/packages/react/src/modal/modal.tsx
index 6054e3bc..0b66095a 100755
--- a/packages/react/src/modal/modal.tsx
+++ b/packages/react/src/modal/modal.tsx
@@ -1,6 +1,6 @@
 import React, { useContext, useEffect, useId, useRef, useState } from 'react';
 import classNames from 'classnames';
-import { CSSTransition } from 'react-transition-group';
+import Transition from '../transition';
 import Overlay from '../overlay';
 import Button from '../button/button';
 import Flex from '../flex/flex';
@@ -132,11 +132,12 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>((props, ref) => {
       style={maskStyle}>
       <div ref={ref} className={cls} style={{ top }}>
         <div style={{ width, ...style }}>
-          <CSSTransition
+          <Transition
             appear={true}
             nodeRef={nodeRef}
             in={modalVisible}
             classNames={`${prefixCls}__content_${animation}`}
+            unmountOnExit={false}
             timeout={0}>
             <div
               ref={nodeRef}
@@ -160,7 +161,7 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>((props, ref) => {
               </div>
               {renderFooter()}
             </div>
-          </CSSTransition>
+          </Transition>
         </div>
       </div>
     </Overlay>
diff --git a/packages/react/src/overlay/overlay.tsx b/packages/react/src/overlay/overlay.tsx
index 9913b9f8..15a29277 100755
--- a/packages/react/src/overlay/overlay.tsx
+++ b/packages/react/src/overlay/overlay.tsx
@@ -1,7 +1,7 @@
 import { useContext, useEffect, useRef } from 'react';
 import classNames from 'classnames';
 import Portal from '../portal';
-import { CSSTransition } from 'react-transition-group';
+import Transition from '../transition';
 import { ConfigContext } from '../config-provider/config-context';
 import { getPrefixCls } from '../_utils/general';
 import { OverlayProps } from './types';
@@ -47,7 +47,7 @@ const Overlay = (props: OverlayProps): JSX.Element => {
 
   return (
     <Portal>
-      <CSSTransition
+      <Transition
         appear={true}
         nodeRef={nodeRef}
         onEnter={onEnter}
@@ -62,7 +62,7 @@ const Overlay = (props: OverlayProps): JSX.Element => {
         <div ref={nodeRef} tabIndex={-1} className={cls} onClick={clickCallback} style={{ zIndex, ...style }}>
           {children}
         </div>
-      </CSSTransition>
+      </Transition>
     </Portal>
   );
 };
diff --git a/packages/react/src/transition/__tests__/__snapshots__/transition.test.tsx.snap b/packages/react/src/transition/__tests__/__snapshots__/transition.test.tsx.snap
index cb1ad7d0..fbed1eb9 100644
--- a/packages/react/src/transition/__tests__/__snapshots__/transition.test.tsx.snap
+++ b/packages/react/src/transition/__tests__/__snapshots__/transition.test.tsx.snap
@@ -3,7 +3,7 @@
 exports[`<Transition /> should match the snapshot 1`] = `
 <DocumentFragment>
   <div
-    class="ty-zoom-top-appear ty-zoom-top-appear-active"
+    class="ty-zoom-top-enter"
   >
     Content
   </div>
diff --git a/packages/react/src/transition/index.tsx b/packages/react/src/transition/index.tsx
index fc7dd42c..81a2031f 100755
--- a/packages/react/src/transition/index.tsx
+++ b/packages/react/src/transition/index.tsx
@@ -1,4 +1,6 @@
 import Transition from './transition';
 
 export type { AnimationName, TransitionProps } from './transition';
+export { default as useTransition } from './use-transition';
+export type { TransitionState, UseTransitionOptions, UseTransitionResult } from './use-transition';
 export default Transition;
diff --git a/packages/react/src/transition/transition.tsx b/packages/react/src/transition/transition.tsx
index 87e42335..65a7044f 100755
--- a/packages/react/src/transition/transition.tsx
+++ b/packages/react/src/transition/transition.tsx
@@ -1,6 +1,5 @@
 import React from 'react';
-import { CSSTransition } from 'react-transition-group';
-import { CSSTransitionProps } from 'react-transition-group/CSSTransition';
+import useTransition, { TransitionState } from './use-transition';
 
 export type AnimationName =
   | 'zoom-center-top'
@@ -23,42 +22,112 @@ export type AnimationName =
   | 'slide-down';
 
 export type TransitionProps = {
+  in?: boolean;
+  timeout?: number | { enter: number; exit: number };
+  appear?: boolean;
+  unmountOnExit?: boolean;
+  mountOnEnter?: boolean;
+
   /** Animation prefix */
   prefix?: string;
 
   /** Preset animation name */
   animation?: AnimationName;
 
+  /** Custom class name base (overrides prefix + animation) */
+  classNames?: string;
+
   /** Prevent the transition conflict with the inner component */
   wrapper?: boolean;
+
+  nodeRef?: React.RefObject<HTMLElement | null>;
+
+  onEnter?: () => void;
+  onEntering?: () => void;
+  onEntered?: () => void;
+  onExit?: () => void;
+  onExiting?: () => void;
+  onExited?: () => void;
+
   children?: React.ReactNode;
-} & Partial<CSSTransitionProps<HTMLElement>>;
+};
+
+function getTransitionClasses(base: string, state: TransitionState): string {
+  switch (state) {
+    case 'enter':
+      return `${base}-enter`;
+    case 'entering':
+      return `${base}-enter ${base}-enter-active`;
+    case 'entered':
+      return `${base}-enter-done`;
+    case 'exit':
+      return `${base}-exit`;
+    case 'exiting':
+      return `${base}-exit ${base}-exit-active`;
+    case 'exited':
+      return `${base}-exit-done`;
+    default:
+      return '';
+  }
+}
 
-const Transition = (props: TransitionProps): React.ReactElement => {
+const Transition = (props: TransitionProps): React.ReactElement | null => {
   const {
+    in: inProp = false,
     timeout = 300,
     unmountOnExit = true,
+    mountOnEnter,
     appear = true,
     prefix = 'ty',
     animation,
-    classNames,
+    classNames: classNamesProp,
     nodeRef,
     children,
     wrapper,
-    ...otherProps
+    onEnter,
+    onEntering,
+    onEntered,
+    onExit,
+    onExiting,
+    onExited,
   } = props;
 
-  return (
-    <CSSTransition
-      {...(otherProps as CSSTransitionProps<HTMLElement>)}
-      timeout={timeout}
-      appear={appear}
-      unmountOnExit={unmountOnExit}
-      nodeRef={nodeRef}
-      classNames={classNames ? classNames : `${prefix}-${animation}`}>
-      {wrapper ? <div>{children}</div> : (children as React.ReactElement)}
-    </CSSTransition>
-  );
+  const { state, shouldMount } = useTransition({
+    in: inProp,
+    timeout,
+    appear,
+    unmountOnExit,
+    mountOnEnter,
+    onEnter,
+    onEntering,
+    onEntered,
+    onExit,
+    onExiting,
+    onExited,
+    nodeRef,
+  });
+
+  if (!shouldMount) {
+    return null;
+  }
+
+  const base = classNamesProp ? classNamesProp : `${prefix}-${animation}`;
+  const transitionClasses = getTransitionClasses(base, state);
+
+  const child = wrapper ? <div>{children}</div> : children;
+
+  if (React.isValidElement(child)) {
+    const existingClassName = (child.props as { className?: string }).className || '';
+    const mergedClassName = existingClassName
+      ? `${existingClassName} ${transitionClasses}`.trim()
+      : transitionClasses;
+
+    return React.cloneElement(child as React.ReactElement<{ className?: string }>, {
+      className: mergedClassName || undefined,
+    });
+  }
+
+  return child as React.ReactElement;
 };
 
 Transition.displayName = 'Transition';
diff --git a/packages/react/src/transition/use-transition.ts b/packages/react/src/transition/use-transition.ts
new file mode 100644
index 00000000..c7f1bc95
--- /dev/null
+++ b/packages/react/src/transition/use-transition.ts
@@ -0,0 +1,217 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+export type TransitionState =
+  | 'unmounted'
+  | 'enter'
+  | 'entering'
+  | 'entered'
+  | 'exit'
+  | 'exiting'
+  | 'exited';
+
+export interface UseTransitionOptions {
+  in: boolean;
+  timeout?: number | { enter: number; exit: number };
+  appear?: boolean;
+  unmountOnExit?: boolean;
+  mountOnEnter?: boolean;
+  onEnter?: () => void;
+  onEntering?: () => void;
+  onEntered?: () => void;
+  onExit?: () => void;
+  onExiting?: () => void;
+  onExited?: () => void;
+  nodeRef?: React.RefObject<HTMLElement | null>;
+}
+
+export interface UseTransitionResult {
+  state: TransitionState;
+  shouldMount: boolean;
+}
+
+function normalizeTimeout(
+  timeout: number | { enter: number; exit: number } | undefined
+): { enter: number; exit: number } {
+  if (timeout == null) return { enter: 300, exit: 300 };
+  if (typeof timeout === 'number') return { enter: timeout, exit: timeout };
+  return timeout;
+}
+
+function useTransition(options: UseTransitionOptions): UseTransitionResult {
+  const {
+    in: inProp,
+    timeout,
+    appear = true,
+    unmountOnExit = true,
+    mountOnEnter = false,
+    onEnter,
+    onEntering,
+    onEntered,
+    onExit,
+    onExiting,
+    onExited,
+    nodeRef,
+  } = options;
+
+  const normalizedTimeout = normalizeTimeout(timeout);
+
+  // Determine initial state
+  const getInitialState = (): TransitionState => {
+    if (inProp) {
+      return appear ? 'enter' : 'entered';
+    }
+    if (unmountOnExit || mountOnEnter) {
+      return 'unmounted';
+    }
+    return 'exited';
+  };
+
+  const [state, setState] = useState<TransitionState>(getInitialState);
+  const rafRef = useRef<number>(0);
+  const timerRef = useRef<number>(0);
+  const transitionEndRef = useRef<(() => void) | null>(null);
+  const initialMountRef = useRef(true);
+
+  // Store latest callbacks in refs to avoid re-triggering effects
+  const callbacksRef = useRef({
+    onEnter,
+    onEntering,
+    onEntered,
+    onExit,
+    onExiting,
+    onExited,
+  });
+  callbacksRef.current = {
+    onEnter,
+    onEntering,
+    onEntered,
+    onExit,
+    onExiting,
+    onExited,
+  };
+
+  const cleanup = useCallback(() => {
+    if (rafRef.current) {
+      cancelAnimationFrame(rafRef.current);
+      rafRef.current = 0;
+    }
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = 0;
+    }
+    if (transitionEndRef.current && nodeRef?.current) {
+      nodeRef.current.removeEventListener('transitionend', transitionEndRef.current);
+      transitionEndRef.current = null;
+    }
+  }, [nodeRef]);
+
+  const waitForTransition = useCallback(
+    (phase: 'enter' | 'exit', done: () => void) => {
+      const safetyDuration =
+        phase === 'enter' ? normalizedTimeout.enter : normalizedTimeout.exit;
+
+      // timeout=0 means "don't wait" — advance immediately.
+      // This matches react-transition-group's behavior where timeout=0
+      // skips straight to the done state, letting CSS handle the animation
+      // via the base element's transition property.
+      if (safetyDuration === 0) {
+        done();
+        return;
+      }
+
+      const finish = () => {
+        cleanup();
+        done();
+      };
+
+      // Try transitionend listener first
+      const node = nodeRef?.current;
+      if (node) {
+        const handler = (e: Event) => {
+          if ((e as TransitionEvent).target === node) {
+            finish();
+          }
+        };
+        transitionEndRef.current = handler as () => void;
+        node.addEventListener('transitionend', handler);
+      }
+
+      // Safety timeout fallback
+      timerRef.current = window.setTimeout(finish, safetyDuration + 50);
+    },
+    [cleanup, nodeRef, normalizedTimeout.enter, normalizedTimeout.exit]
+  );
+
+  // Continue the enter animation after DOM is committed (state === 'enter').
+  // useLayoutEffect fires synchronously after DOM mutations, guaranteeing
+  // the child is mounted and refs are populated before onEnter runs.
+  useLayoutEffect(() => {
+    if (state === 'enter') {
+      callbacksRef.current.onEnter?.();
+
+      // Single rAF: useLayoutEffect runs before paint, so one rAF is enough
+      // to ensure the browser has painted the -enter class before we add -enter-active.
+      rafRef.current = requestAnimationFrame(() => {
+        setState('entering');
+        callbacksRef.current.onEntering?.();
+
+        waitForTransition('enter', () => {
+          setState('entered');
+          callbacksRef.current.onEntered?.();
+        });
+      });
+    }
+  }, [state]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Continue the exit animation after DOM reflects exit state
+  useLayoutEffect(() => {
+    if (state === 'exit') {
+      callbacksRef.current.onExit?.();
+
+      rafRef.current = requestAnimationFrame(() => {
+        setState('exiting');
+        callbacksRef.current.onExiting?.();
+
+        waitForTransition('exit', () => {
+          setState((prev) => {
+            if (prev === 'exiting') {
+              callbacksRef.current.onExited?.();
+              return unmountOnExit ? 'unmounted' : 'exited';
+            }
+            return prev;
+          });
+        });
+      });
+    }
+  }, [state]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // React to `in` prop changes — only set the initial phase state.
+  // The useLayoutEffect above handles the rest after DOM commit.
+  useEffect(() => {
+    if (initialMountRef.current) {
+      initialMountRef.current = false;
+      // On initial mount with appear=true, state is already 'enter' from getInitialState,
+      // and the useLayoutEffect above will pick it up.
+      return;
+    }
+
+    if (inProp) {
+      cleanup();
+      setState('enter');
+    } else {
+      cleanup();
+      setState('exit');
+    }
+  }, [inProp]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return cleanup;
+  }, [cleanup]);
+
+  const shouldMount = state !== 'unmounted';
+
+  return { state, shouldMount };
+}
+
+export default useTransition;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 86bf3d99..fc88a7c0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -174,9 +174,6 @@ importers:
       classnames:
         specifier: ^2.3.1
         version: 2.5.1
-      react-transition-group:
-        specifier: ^4.4.2
-        version: 4.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       tslib:
         specifier: ^2.3.1
         version: 2.8.1
@@ -196,9 +193,6 @@ importers:
       '@types/react-dom':
         specifier: ^18.2.0
         version: 18.3.7(@types/react@18.3.28)
-      '@types/react-transition-group':
-        specifier: ^4.4.4
-        version: 4.4.12(@types/react@18.3.28)
       autoprefixer:
         specifier: ^10.4.4
         version: 10.4.27(postcss@8.5.8)
@@ -1376,11 +1370,6 @@ packages:
     peerDependencies:
       '@types/react': ^18.0.0
 
-  '@types/react-transition-group@4.4.12':
-    resolution: {integrity: sha512-8TV6R3h2j7a91c+1DXdJi3Syo69zzIZbz7Lg5tORM5LEJG7X/E6a1V3drRyBRZq7/utz7A+c4OgYLiLcYGHG6w==}
-    peerDependencies:
-      '@types/react': '*'
-
   '@types/react@18.3.28':
     resolution: {integrity: sha512-z9VXpC7MWrhfWipitjNdgCauoMLRdIILQsAEV+ZesIzBq/oUlxk0m3ApZuMFCXdnS4U7KrI+l3WRUEGQ8K1QKw==}
 
@@ -2166,9 +2155,6 @@ packages:
   dom-accessibility-api@0.6.3:
     resolution: {integrity: sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==}
 
-  dom-helpers@5.2.1:
-    resolution: {integrity: sha512-nRCa7CK3VTrM2NmGkIy4cbK7IZlgBE/PYMn55rrXefr5xXDP0LdtfPnblFDoVdcAfslJ7or6iqAUnx0CCGIWQA==}
-
   domexception@4.0.0:
     resolution: {integrity: sha512-A2is4PLG+eeSfoTMA95/s4pvAoSo2mKtiM5jlHkAVewmiO8ISFTFKZjH7UAM1Atli/OT/7JHOrJRJiMKUZKYBw==}
     engines: {node: '>=12'}
@@ -4245,12 +4231,6 @@ packages:
       react: ^16.0.0 || ^17 || ^18
       react-dom: ^16.0.0 || ^17 || ^18
 
-  react-transition-group@4.4.5:
-    resolution: {integrity: sha512-pZcd1MCJoiKiBR2NRxeCRg13uCXbydPnmB4EOeRrY7480qNWO8IIgQG6zlDkm6uRMsURXPuKq0GWtiM59a5Q6g==}
-    peerDependencies:
-      react: '>=16.6.0'
-      react-dom: '>=16.6.0'
-
   react@18.3.1:
     resolution: {integrity: sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==}
     engines: {node: '>=0.10.0'}
@@ -6548,10 +6528,6 @@ snapshots:
     dependencies:
       '@types/react': 18.3.28
 
-  '@types/react-transition-group@4.4.12(@types/react@18.3.28)':
-    dependencies:
-      '@types/react': 18.3.28
-
   '@types/react@18.3.28':
     dependencies:
       '@types/prop-types': 15.7.15
@@ -7439,11 +7415,6 @@ snapshots:
 
   dom-accessibility-api@0.6.3: {}
 
-  dom-helpers@5.2.1:
-    dependencies:
-      '@babel/runtime': 7.28.6
-      csstype: 3.2.3
-
   domexception@4.0.0:
     dependencies:
       webidl-conversions: 7.0.0
@@ -10235,15 +10206,6 @@ snapshots:
       react-dom: 18.3.1(react@18.3.1)
       sucrase: 3.35.1
 
-  react-transition-group@4.4.5(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
-    dependencies:
-      '@babel/runtime': 7.28.6
-      dom-helpers: 5.2.1
-      loose-envify: 1.4.0
-      prop-types: 15.8.1
-      react: 18.3.1
-      react-dom: 18.3.1(react@18.3.1)
-
   react@18.3.1:
     dependencies:
       loose-envify: 1.4.0

From 0be4ab93191f563bf568d6d377ab251897e3dced Mon Sep 17 00:00:00 2001
From: wangdicoder <wangdicoder@gmail.com>
Date: Sat, 21 Mar 2026 21:28:52 +1100
Subject: [PATCH 2/3] fix: update waterfall component

---
 .../__snapshots__/waterfall.test.tsx.snap     |  10 +-
 packages/react/src/waterfall/waterfall.tsx    | 123 ++++++++++++------
 2 files changed, 86 insertions(+), 47 deletions(-)

diff --git a/packages/react/src/waterfall/__tests__/__snapshots__/waterfall.test.tsx.snap b/packages/react/src/waterfall/__tests__/__snapshots__/waterfall.test.tsx.snap
index 7544b768..4bbbf3b4 100644
--- a/packages/react/src/waterfall/__tests__/__snapshots__/waterfall.test.tsx.snap
+++ b/packages/react/src/waterfall/__tests__/__snapshots__/waterfall.test.tsx.snap
@@ -7,7 +7,7 @@ exports[`<Waterfall /> should match the snapshot 1`] = `
     style="position: relative; height: 16px;"
   >
     <div
-      class="ty-waterfall__item"
+      class="ty-waterfall__item ty-waterfall__item-fade-enter-done"
       style="position: absolute; top: 0px; transition: top 0.3s ease, left 0.3s ease, opacity 0.3s ease; opacity: 1;"
     >
       <div
@@ -17,7 +17,7 @@ exports[`<Waterfall /> should match the snapshot 1`] = `
       </div>
     </div>
     <div
-      class="ty-waterfall__item"
+      class="ty-waterfall__item ty-waterfall__item-fade-enter-done"
       style="position: absolute; top: 0px; transition: top 0.3s ease, left 0.3s ease, opacity 0.3s ease; opacity: 1;"
     >
       <div
@@ -27,7 +27,7 @@ exports[`<Waterfall /> should match the snapshot 1`] = `
       </div>
     </div>
     <div
-      class="ty-waterfall__item"
+      class="ty-waterfall__item ty-waterfall__item-fade-enter-done"
       style="position: absolute; top: 0px; transition: top 0.3s ease, left 0.3s ease, opacity 0.3s ease; opacity: 1;"
     >
       <div
@@ -37,7 +37,7 @@ exports[`<Waterfall /> should match the snapshot 1`] = `
       </div>
     </div>
     <div
-      class="ty-waterfall__item"
+      class="ty-waterfall__item ty-waterfall__item-fade-enter-done"
       style="position: absolute; top: 16px; transition: top 0.3s ease, left 0.3s ease, opacity 0.3s ease; opacity: 1;"
     >
       <div
@@ -47,7 +47,7 @@ exports[`<Waterfall /> should match the snapshot 1`] = `
       </div>
     </div>
     <div
-      class="ty-waterfall__item"
+      class="ty-waterfall__item ty-waterfall__item-fade-enter-done"
       style="position: absolute; top: 16px; transition: top 0.3s ease, left 0.3s ease, opacity 0.3s ease; opacity: 1;"
     >
       <div
diff --git a/packages/react/src/waterfall/waterfall.tsx b/packages/react/src/waterfall/waterfall.tsx
index 7cad9da7..710b02ef 100644
--- a/packages/react/src/waterfall/waterfall.tsx
+++ b/packages/react/src/waterfall/waterfall.tsx
@@ -1,6 +1,6 @@
 import React, { useCallback, useContext, useEffect, useRef, useState } from 'react';
 import classNames from 'classnames';
-import { CSSTransition, TransitionGroup } from 'react-transition-group';
+import Transition from '../transition';
 import { ConfigContext } from '../config-provider/config-context';
 import { getPrefixCls } from '../_utils/general';
 import { Breakpoint, WaterfallItem, WaterfallProps } from './types';
@@ -115,6 +115,42 @@ const Waterfall = React.forwardRef<HTMLDivElement, WaterfallProps>((props, ref)
     onLayoutChange(sortInfo);
   }, [itemPositions, items, onLayoutChange]);
 
+  // ============== Exiting items (replaces TransitionGroup) ==============
+  const prevItemsRef = useRef<WaterfallItem[]>(items || []);
+  const [exitingItems, setExitingItems] = useState<Map<React.Key, WaterfallItem>>(new Map());
+
+  useEffect(() => {
+    const currentKeys = new Set((items || []).map((item, i) => item.key ?? i));
+    const removed = new Map<React.Key, WaterfallItem>();
+
+    prevItemsRef.current.forEach((item, index) => {
+      const key = item.key ?? index;
+      if (!currentKeys.has(key)) {
+        removed.set(key, item);
+      }
+    });
+
+    if (removed.size > 0) {
+      setExitingItems((prev) => {
+        const next = new Map(prev);
+        removed.forEach((item, key) => next.set(key, item));
+        return next;
+      });
+    }
+
+    prevItemsRef.current = items || [];
+  }, [items]);
+
+  const handleExited = useCallback((key: React.Key) => {
+    itemRefsMap.current.delete(key);
+    setExitingItems((prev) => {
+      const next = new Map(prev);
+      next.delete(key);
+      return next;
+    });
+    collectItemSizes();
+  }, [collectItemSizes]);
+
   // ==================== Render ====================
   const cls = classNames(prefixCls, className);
 
@@ -126,6 +162,46 @@ const Waterfall = React.forwardRef<HTMLDivElement, WaterfallProps>((props, ref)
 
   const mergedItems = items || [];
 
+  const renderItem = (item: WaterfallItem, index: number, isExiting: boolean) => {
+    const key = item.key ?? index;
+    const position = itemPositions.get(key);
+    const hasPosition = !!position;
+    const columnIndex = position?.column ?? 0;
+
+    const itemStyle: React.CSSProperties = {
+      position: 'absolute',
+      width: `calc((100% - ${horizontalGutter * (columnCount - 1)}px) / ${columnCount})`,
+      left: `calc((100% - ${horizontalGutter * (columnCount - 1)}px) / ${columnCount} * ${columnIndex} + ${horizontalGutter * columnIndex}px)`,
+      top: position?.top ?? 0,
+      // Only transition position changes after initial placement
+      transition: hasPosition ? 'top 0.3s ease, left 0.3s ease, opacity 0.3s ease' : 'none',
+      // Hide until position is computed so items don't flash at (0,0)
+      opacity: hasPosition ? 1 : 0,
+    };
+
+    const content = item.children ?? itemRender?.({ ...item, index, column: columnIndex });
+
+    return (
+      <Transition
+        key={key}
+        in={!isExiting}
+        timeout={300}
+        appear={false}
+        unmountOnExit={true}
+        classNames={`${prefixCls}__item-fade`}
+        onExited={() => handleExited(key)}
+      >
+        <div
+          ref={(el) => setItemRef(key, el)}
+          className={`${prefixCls}__item`}
+          style={itemStyle}
+        >
+          {content}
+        </div>
+      </Transition>
+    );
+  };
+
   return (
     <div
       ref={ref}
@@ -135,47 +211,10 @@ const Waterfall = React.forwardRef<HTMLDivElement, WaterfallProps>((props, ref)
       onLoad={collectItemSizes}
       onError={collectItemSizes}
     >
-      <TransitionGroup component={null}>
-        {mergedItems.map((item, index) => {
-          const key = item.key ?? index;
-          const position = itemPositions.get(key);
-          const hasPosition = !!position;
-          const columnIndex = position?.column ?? 0;
-
-          const itemStyle: React.CSSProperties = {
-            position: 'absolute',
-            width: `calc((100% - ${horizontalGutter * (columnCount - 1)}px) / ${columnCount})`,
-            left: `calc((100% - ${horizontalGutter * (columnCount - 1)}px) / ${columnCount} * ${columnIndex} + ${horizontalGutter * columnIndex}px)`,
-            top: position?.top ?? 0,
-            // Only transition position changes after initial placement
-            transition: hasPosition ? 'top 0.3s ease, left 0.3s ease, opacity 0.3s ease' : 'none',
-            // Hide until position is computed so items don't flash at (0,0)
-            opacity: hasPosition ? 1 : 0,
-          };
-
-          const content = item.children ?? itemRender?.({ ...item, index, column: columnIndex });
-
-          return (
-            <CSSTransition
-              key={key}
-              timeout={300}
-              classNames={`${prefixCls}__item-fade`}
-              onExited={() => {
-                itemRefsMap.current.delete(key);
-                collectItemSizes();
-              }}
-            >
-              <div
-                ref={(el) => setItemRef(key, el)}
-                className={`${prefixCls}__item`}
-                style={itemStyle}
-              >
-                {content}
-              </div>
-            </CSSTransition>
-          );
-        })}
-      </TransitionGroup>
+      {mergedItems.map((item, index) => renderItem(item, index, false))}
+      {Array.from(exitingItems.entries()).map(([key, item]) =>
+        renderItem(item, Number(key), true)
+      )}
     </div>
   );
 });

From bfbc83d7a3af353e60df94fc864140db2cb99f13 Mon Sep 17 00:00:00 2001
From: wangdicoder <wangdicoder@gmail.com>
Date: Sat, 21 Mar 2026 21:29:36 +1100
Subject: [PATCH 3/3] chore: add changeset for react-transition-group removal

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .changeset/replace-react-transition-group.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/replace-react-transition-group.md

diff --git a/.changeset/replace-react-transition-group.md b/.changeset/replace-react-transition-group.md
new file mode 100644
index 00000000..ce89321d
--- /dev/null
+++ b/.changeset/replace-react-transition-group.md
@@ -0,0 +1,5 @@
+---
+"@tiny-design/react": minor
+---
+
+Replace react-transition-group with a custom useTransition hook for CSS-driven animations. This removes the unmaintained dependency and prepares the library for React 19 compatibility.