feat(Splitter): add smooth transition animation for collapsible panels (#56814)

* feat(Splitter): add smooth transition animation for collapsible panels

* fix: clear timeout on rapid clicks and sync with motionDurationMid token

* fix: add initial value to useRef for TypeScript strict mode

* perf: inline collapse animation logic to reduce bundle size

* fix: use token.motionDurationMid instead of hard-coded duration for collapse animation

* feat: add splitter collapse animation option

* refactor: change collapseAnimation to collapseDuration (number | boolean)

* test: add coverage for Panel style default value

* perf: optimize bundle size by inlining functions and simplifying logic

* fix: address code review feedback for collapse animation

* Ensure 100% code coverage percent

* Fix the lint test for splitter

* ensure Splitter collapsible variable

* Ensure the code coverage percent

* Fix Splitter collapse functionality

* Update components/splitter/index.zh-CN.md

Co-authored-by: afc163 <afc163@gmail.com>
Signed-off-by: NeedmeFordev <124189514+spider-yamet@users.noreply.github.com>

* feat: Simplify the logic

* feat: add toggle for motion in collapsible splitter demo

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: clean up

* refactor: no recording

* chore: rm AI uselsss test

* chore: clean up

* test: update test case

* test: clean up

---------

Signed-off-by: NeedmeFordev <124189514+spider-yamet@users.noreply.github.com>
Co-authored-by: 遇见同学 <1875694521@qq.com>
Co-authored-by: Wanpan <wanpan96@163.com>
Co-authored-by: thinkasany <480968828@qq.com>
Co-authored-by: afc163 <afc163@gmail.com>
Co-authored-by: 二货机器人 <smith3816@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: lijianan <574980606@qq.com>

components/app/App.tsx

@@ -21,7 +21,7 @@ export interface AppProps<P = AnyObject> extends AppConfig {
   component?: CustomComponent<P> | false;
 }
 
-const App: React.FC<AppProps> = (props) => {
+const App = React.forwardRef<HTMLElement, AppProps>((props, ref) => {
   const {
     prefixCls: customizePrefixCls,
     children,
@@ -79,6 +79,12 @@ const App: React.FC<AppProps> = (props) => {
     'When using cssVar, ensure `component` is assigned a valid React component string.',
   );
 
+  devUseWarning('App')(
+    !ref || component !== false,
+    'usage',
+    '`ref` is not supported when `component` is `false`. Please provide a valid `component` instead.',
+  );
+
   // ============================ Render ============================
   const Component = component === false ? React.Fragment : component;
 
@@ -90,7 +96,7 @@ const App: React.FC<AppProps> = (props) => {
   return (
     <AppContext.Provider value={memoizedContextValue}>
       <AppConfigContext.Provider value={mergedAppConfig}>
-        <Component {...(component === false ? undefined : rootProps)}>
+        <Component {...(component === false ? undefined : { ...rootProps, ref })}>
           {ModalContextHolder}
           {messageContextHolder}
           {notificationContextHolder}
@@ -99,7 +105,7 @@ const App: React.FC<AppProps> = (props) => {
       </AppConfigContext.Provider>
     </AppContext.Provider>
   );
-};
+});
 
 if (process.env.NODE_ENV !== 'production') {
   App.displayName = 'App';

components/app/__tests__/index.test.tsx

@@ -247,5 +247,20 @@ describe('App', () => {
         'Warning: [antd: App] When using cssVar, ensure `component` is assigned a valid React component string.',
       );
     });
+
+    it('should warn if component is false and ref is not empty', () => {
+      const domRef = React.createRef<HTMLSpanElement>();
+      render(<App ref={domRef} component={false} />);
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        'Warning: [antd: App] `ref` is not supported when `component` is `false`. Please provide a valid `component` instead.',
+      );
+    });
+
+    it('App should support Ref', () => {
+      const domRef = React.createRef<HTMLSpanElement>();
+      const { container } = render(<App ref={domRef} className="bamboo" component="span" />);
+      expect(domRef.current).toBe(container.querySelector('.bamboo'));
+    });
   });
 });

components/config-provider/__tests__/theme.test.tsx

@@ -2,7 +2,7 @@ import React, { useEffect } from 'react';
 import { Modal } from 'antd';
 
 import ConfigProvider from '..';
-import { Button, InputNumber, Select } from '../..';
+import { Button, InputNumber, Select, Space } from '../..';
 import { render, waitFakeTimer } from '../../../tests/utils';
 import theme from '../../theme';
 import type { GlobalToken } from '../../theme/internal';
@@ -113,6 +113,21 @@ describe('ConfigProvider.Theme', () => {
     ).toBeTruthy();
   });
 
+  it('should support Addon component token', () => {
+    const { container } = render(
+      <ConfigProvider theme={{ components: { Addon: { colorText: '#0000FF', algorithm: true } } }}>
+        <Space.Compact>
+          <Space.Addon className="test-addon">Addon Content</Space.Addon>
+        </Space.Compact>
+      </ConfigProvider>,
+    );
+
+    const addon = container.querySelector('.test-addon')!;
+    expect(addon).toHaveStyle({
+      '--ant-color-text': '#0000FF',
+    });
+  });
+
   it('hashed should be true if not changed', () => {
     let hashId = 'hashId';
 

components/select/style/dropdown.ts

@@ -121,10 +121,6 @@ const genSingleStyle: GenerateStyle<SelectToken> = (token) => {
               alignItems: 'center',
             },
 
-            [`&-active:not(${selectItemCls}-option-disabled)`]: {
-              backgroundColor: token.optionActiveBg,
-            },
-
             [`&-selected:not(${selectItemCls}-option-disabled)`]: {
               color: token.optionSelectedColor,
               fontWeight: token.optionSelectedFontWeight,
@@ -135,6 +131,10 @@ const genSingleStyle: GenerateStyle<SelectToken> = (token) => {
               },
             },
 
+            [`&-active:not(${selectItemCls}-option-disabled)`]: {
+              backgroundColor: token.optionActiveBg,
+            },
+
             '&-disabled': {
               [`&${selectItemCls}-option-selected`]: {
                 backgroundColor: token.colorBgContainerDisabled,

components/space/__tests__/__snapshots__/demo-extend.test.ts.snap

@@ -16066,6 +16066,28 @@ exports[`renders components/space/demo/compact-nested.tsx extend context correct
 
 exports[`renders components/space/demo/compact-nested.tsx extend context correctly 2`] = `[]`;
 
+exports[`renders components/space/demo/component-token.tsx extend context correctly 1`] = `
+<div
+  class="ant-space-compact"
+>
+  <div
+    class="ant-space-addon ant-space-addon-compact-item ant-space-addon-compact-first-item css-var-test-id ant-space-addon-variant-outlined"
+  >
+    Addon
+  </div>
+  <button
+    class="ant-btn css-var-test-id ant-btn-primary ant-btn-color-primary ant-btn-variant-solid ant-btn-compact-item ant-btn-compact-last-item"
+    type="button"
+  >
+    <span>
+      Button
+    </span>
+  </button>
+</div>
+`;
+
+exports[`renders components/space/demo/component-token.tsx extend context correctly 2`] = `[]`;
+
 exports[`renders components/space/demo/debug.tsx extend context correctly 1`] = `
 <div
   class="ant-space ant-space-horizontal ant-space-align-center ant-space-gap-row-small ant-space-gap-col-small css-var-test-id"

components/space/__tests__/__snapshots__/demo.test.tsx.snap

@@ -4097,6 +4097,26 @@ exports[`renders components/space/demo/compact-nested.tsx correctly 1`] = `
 </div>
 `;
 
+exports[`renders components/space/demo/component-token.tsx correctly 1`] = `
+<div
+  class="ant-space-compact"
+>
+  <div
+    class="ant-space-addon ant-space-addon-compact-item ant-space-addon-compact-first-item css-var-test-id ant-space-addon-variant-outlined"
+  >
+    Addon
+  </div>
+  <button
+    class="ant-btn css-var-test-id ant-btn-primary ant-btn-color-primary ant-btn-variant-solid ant-btn-compact-item ant-btn-compact-last-item"
+    type="button"
+  >
+    <span>
+      Button
+    </span>
+  </button>
+</div>
+`;
+
 exports[`renders components/space/demo/debug.tsx correctly 1`] = `
 <div
   class="ant-space ant-space-horizontal ant-space-align-center ant-space-gap-row-small ant-space-gap-col-small css-var-test-id"

components/space/demo/component-token.md

@@ -0,0 +1,7 @@
+## zh-CN
+
+使用 `ConfigProvider` 自定义 `Space.Addon` 的主题样式。
+
+## en-US
+
+Use `ConfigProvider` to customize the theme of `Space.Addon`.

components/space/demo/component-token.tsx

@@ -0,0 +1,19 @@
+import React from 'react';
+import { Button, ConfigProvider, Space } from 'antd';
+
+const App: React.FC = () => (
+  <ConfigProvider
+    theme={{
+      components: {
+        Addon: { colorText: 'blue', algorithm: true },
+      },
+    }}
+  >
+    <Space.Compact>
+      <Space.Addon>Addon</Space.Addon>
+      <Button type="primary">Button</Button>
+    </Space.Compact>
+  </ConfigProvider>
+);
+
+export default App;

components/space/index.en-US.md

@@ -34,6 +34,7 @@ coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*37T2R6O9oi0AAA
 <code src="./demo/debug.tsx" debug>Diverse Child</code>
 <code src="./demo/gap-in-line.tsx" debug>Flex gap style</code>
 <code src="./demo/style-class.tsx" version="6.0.0">Custom semantic dom styling</code>
+<code src="./demo/component-token.tsx" debug>Customize Addon with theme</code>
 
 ## API
 

components/space/index.zh-CN.md

@@ -38,6 +38,7 @@ coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*37T2R6O9oi0AAA
 <code src="./demo/debug.tsx" debug>多样的 Child</code>
 <code src="./demo/gap-in-line.tsx" debug>Flex gap 样式</code>
 <code src="./demo/style-class.tsx" version="6.0.0">自定义语义结构的样式和类</code>
+<code src="./demo/component-token.tsx" debug>自定义主题</code>
 
 ## API
 

components/space/style/addon.ts

@@ -1,3 +1,4 @@
+import { resetComponent } from '../../style';
 import { genCompactItemStyle } from '../../style/compact-item';
 import { genStyleHooks } from '../../theme/internal';
 import type { FullToken, GenerateStyle } from '../../theme/internal';
@@ -7,11 +8,11 @@ import { genCssVar } from '../../theme/util/genStyleUtils';
 // biome-ignore lint/suspicious/noEmptyInterface: ComponentToken need to be empty by default
 export interface ComponentToken {}
 
-interface SpaceToken extends FullToken<'Space'> {
+interface AddonToken extends FullToken<'Space'> {
   // Custom token here
 }
 
-const genSpaceAddonStyle: GenerateStyle<SpaceToken> = (token) => {
+const genSpaceAddonStyle: GenerateStyle<AddonToken> = (token) => {
   const {
     componentCls,
     borderRadius,
@@ -27,7 +28,7 @@ const genSpaceAddonStyle: GenerateStyle<SpaceToken> = (token) => {
     antCls,
   } = token;
 
-  const [varName, varRef] = genCssVar(antCls, 'space');
+  const [varName, varRef] = genCssVar(antCls, 'space-addon');
 
   return {
     [componentCls]: [
@@ -35,6 +36,7 @@ const genSpaceAddonStyle: GenerateStyle<SpaceToken> = (token) => {
       // ==                         Base                         ==
       // ==========================================================
       {
+        ...resetComponent(token),
         display: 'inline-flex',
         alignItems: 'center',
         gap: 0,
@@ -144,7 +146,7 @@ const genSpaceAddonStyle: GenerateStyle<SpaceToken> = (token) => {
 };
 
 // ============================== Export ==============================
-export default genStyleHooks(['Space', 'Addon'], (token) => [
+export default genStyleHooks('Addon', (token) => [
   genSpaceAddonStyle(token),
   genCompactItemStyle(token, { focus: false }),
 ]);

components/splitter/Panel.tsx

@@ -7,11 +7,14 @@ export const InternalPanel = forwardRef<
   HTMLDivElement,
   React.PropsWithChildren<InternalPanelProps>
 >((props, ref) => {
-  const { prefixCls, className, children, size, style = {} } = props;
+  const { prefixCls, className, children, size, style = {}, supportMotion } = props;
 
   const panelClassName = clsx(
     `${prefixCls}-panel`,
-    { [`${prefixCls}-panel-hidden`]: size === 0 },
+    {
+      [`${prefixCls}-panel-hidden`]: size === 0,
+      [`${prefixCls}-panel-transition`]: supportMotion,
+    },
     className,
   );
 

components/splitter/Splitter.tsx

@@ -28,6 +28,7 @@ const Splitter: React.FC<React.PropsWithChildren<SplitterProps>> = (props) => {
     prefixCls: customizePrefixCls,
     className,
     classNames,
+    collapsible,
     style,
     styles,
     layout,
@@ -217,9 +218,13 @@ const Splitter: React.FC<React.PropsWithChildren<SplitterProps>> = (props) => {
             style: { ...mergedStyles.panel, ...item.style },
           };
 
-          // Panel
           const panel = (
-            <InternalPanel {...panelProps} prefixCls={prefixCls} size={panelSizes[idx]} />
+            <InternalPanel
+              {...panelProps}
+              prefixCls={prefixCls}
+              size={panelSizes[idx]}
+              supportMotion={collapsible?.motion && movingIndex === undefined}
+            />
           );
 
           // Split Bar

components/splitter/__tests__/__snapshots__/demo-extend.test.ts.snap

@@ -4,12 +4,40 @@ exports[`renders components/splitter/demo/collapsible.tsx extend context correct
 <div
   class="ant-flex css-var-test-id ant-flex-align-stretch ant-flex-gap-middle ant-flex-vertical"
 >
+  <div
+    class="ant-flex css-var-test-id ant-flex-gap-middle"
+  >
+    <button
+      aria-checked="true"
+      class="ant-switch css-var-test-id ant-switch-checked"
+      role="switch"
+      type="button"
+    >
+      <div
+        class="ant-switch-handle"
+      />
+      <span
+        class="ant-switch-inner"
+      >
+        <span
+          class="ant-switch-inner-checked"
+        >
+          motion
+        </span>
+        <span
+          class="ant-switch-inner-unchecked"
+        >
+          motion
+        </span>
+      </span>
+    </button>
+  </div>
   <div
     class="ant-splitter ant-splitter-horizontal css-var-test-id ant-splitter-css-var"
     style="box-shadow: 0 0 10px rgba(0, 0, 0, 0.1); height: 200px;"
   >
     <div
-      class="ant-splitter-panel"
+      class="ant-splitter-panel ant-splitter-panel-transition"
       style="flex-basis: auto; flex-grow: 1;"
     >
       <div
@@ -36,7 +64,7 @@ exports[`renders components/splitter/demo/collapsible.tsx extend context correct
       />
     </div>
     <div
-      class="ant-splitter-panel"
+      class="ant-splitter-panel ant-splitter-panel-transition"
       style="flex-basis: auto; flex-grow: 1;"
     >
       <div
@@ -57,7 +85,7 @@ exports[`renders components/splitter/demo/collapsible.tsx extend context correct
     style="box-shadow: 0 0 10px rgba(0, 0, 0, 0.1); height: 300px;"
   >
     <div
-      class="ant-splitter-panel"
+      class="ant-splitter-panel ant-splitter-panel-transition"
       style="flex-basis: auto; flex-grow: 1;"
     >
       <div
@@ -84,7 +112,7 @@ exports[`renders components/splitter/demo/collapsible.tsx extend context correct
       />
     </div>
     <div
-      class="ant-splitter-panel"
+      class="ant-splitter-panel ant-splitter-panel-transition"
       style="flex-basis: auto; flex-grow: 1;"
     >
       <div

components/splitter/__tests__/__snapshots__/demo.test.ts.snap

@@ -4,12 +4,40 @@ exports[`renders components/splitter/demo/collapsible.tsx correctly 1`] = `
 <div
   class="ant-flex css-var-test-id ant-flex-align-stretch ant-flex-gap-middle ant-flex-vertical"
 >
+  <div
+    class="ant-flex css-var-test-id ant-flex-gap-middle"
+  >
+    <button
+      aria-checked="true"
+      class="ant-switch css-var-test-id ant-switch-checked"
+      role="switch"
+      type="button"
+    >
+      <div
+        class="ant-switch-handle"
+      />
+      <span
+        class="ant-switch-inner"
+      >
+        <span
+          class="ant-switch-inner-checked"
+        >
+          motion
+        </span>
+        <span
+          class="ant-switch-inner-unchecked"
+        >
+          motion
+        </span>
+      </span>
+    </button>
+  </div>
   <div
     class="ant-splitter ant-splitter-horizontal css-var-test-id ant-splitter-css-var"
     style="box-shadow:0 0 10px rgba(0, 0, 0, 0.1);height:200px"
   >
     <div
-      class="ant-splitter-panel"
+      class="ant-splitter-panel ant-splitter-panel-transition"
       style="flex-basis:auto;flex-grow:1"
     >
       <div
@@ -36,7 +64,7 @@ exports[`renders components/splitter/demo/collapsible.tsx correctly 1`] = `
       />
     </div>
     <div
-      class="ant-splitter-panel"
+      class="ant-splitter-panel ant-splitter-panel-transition"
       style="flex-basis:auto;flex-grow:1"
     >
       <div
@@ -57,7 +85,7 @@ exports[`renders components/splitter/demo/collapsible.tsx correctly 1`] = `
     style="box-shadow:0 0 10px rgba(0, 0, 0, 0.1);height:300px"
   >
     <div
-      class="ant-splitter-panel"
+      class="ant-splitter-panel ant-splitter-panel-transition"
       style="flex-basis:auto;flex-grow:1"
     >
       <div
@@ -84,7 +112,7 @@ exports[`renders components/splitter/demo/collapsible.tsx correctly 1`] = `
       />
     </div>
     <div
-      class="ant-splitter-panel"
+      class="ant-splitter-panel ant-splitter-panel-transition"
       style="flex-basis:auto;flex-grow:1"
     >
       <div

components/splitter/__tests__/index.test.tsx

@@ -997,6 +997,21 @@ describe('Splitter', () => {
       expect(onCollapse).toHaveBeenCalledTimes(2);
       expect(onCollapse).toHaveBeenCalledWith([false, false], [50, 50]);
     });
+
+    it('should apply transition when motion is true', async () => {
+      const { container } = render(
+        <SplitterDemo
+          items={[{ collapsible: true }, { collapsible: true }]}
+          collapsible={{
+            motion: true,
+          }}
+        />,
+      );
+
+      expect(container.querySelector('.ant-splitter-panel')).toHaveClass(
+        'ant-splitter-panel-transition',
+      );
+    });
   });
 
   it('auto resize', async () => {

components/splitter/demo/collapsible.tsx

@@ -1,5 +1,5 @@
-import React from 'react';
-import { Flex, Splitter, Typography } from 'antd';
+import React, { useState } from 'react';
+import { Flex, Splitter, Switch, Typography } from 'antd';
 import type { SplitterProps } from 'antd';
 
 const Desc: React.FC<Readonly<{ text?: string | number }>> = (props) => (
@@ -21,11 +21,23 @@ const CustomSplitter: React.FC<Readonly<SplitterProps>> = ({ style, ...restProps
   </Splitter>
 );
 
-const App: React.FC = () => (
-  <Flex gap="middle" vertical>
-    <CustomSplitter style={{ height: 200 }} />
-    <CustomSplitter style={{ height: 300 }} orientation="vertical" />
-  </Flex>
-);
+const App: React.FC = () => {
+  const [motion, setMotion] = useState(true);
+
+  return (
+    <Flex vertical gap="middle">
+      <Flex gap="middle">
+        <Switch
+          checked={motion}
+          onChange={setMotion}
+          checkedChildren="motion"
+          unCheckedChildren="motion"
+        />
+      </Flex>
+      <CustomSplitter style={{ height: 200 }} collapsible={{ motion }} />
+      <CustomSplitter style={{ height: 300 }} orientation="vertical" collapsible={{ motion }} />
+    </Flex>
+  );
+};
 
 export default App;

components/splitter/index.en-US.md

@@ -44,6 +44,7 @@ Common props ref：[Common props](/docs/react/common-props)
 | Property | Description | Type | Default | Version |
 | --- | --- | --- | --- | --- |
 | classNames | Customize class for each semantic structure inside the component. Supports object or function. | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - |  |
+| collapsible | Collapse config. Set `motion: true` to enable collapse animation; duration is controlled by Component Token `panelMotionDuration` (inherits from `motionDurationSlow`) | `{ motion?: boolean }` | - | 6.4.0 |
 | collapsibleIcon | custom collapsible icon | `{start: ReactNode; end: ReactNode}` | - | 6.0.0 |
 | draggerIcon | custom dragger icon | `ReactNode` | - | 6.0.0 |
 | ~~layout~~ | Layout direction | `horizontal` \| `vertical` | `horizontal` | - |

components/splitter/index.zh-CN.md

@@ -45,6 +45,7 @@ demo:
 | 参数 | 说明 | 类型 | 默认值 | 版本 |
 | --- | --- | --- | --- | --- |
 | classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - |  |
+| collapsible | 折叠配置。`motion: true` 时启用折叠动画，时长由组件 Token `panelMotionDuration` 控制（继承自 `motionDurationSlow`） | `{ motion?: boolean }` | - | 6.4.0 |
 | collapsibleIcon | 折叠图标 | `{start?: ReactNode; end?: ReactNode}` | - | 6.0.0 |
 | draggerIcon | 拖拽图标 | `ReactNode` | - | 6.0.0 |
 | ~~layout~~ | 布局方向 | `horizontal` \| `vertical` | `horizontal` | - |

components/splitter/interface.ts

@@ -46,6 +46,10 @@ export interface SplitterProps {
   prefixCls?: string;
   className?: string;
   classNames?: SplitterClassNamesType;
+  /**
+   * Collapse configuration. Set `motion: true` to enable collapse animation (duration follows Component Token).
+   */
+  collapsible?: { motion?: boolean };
   style?: React.CSSProperties;
   styles?: SplitterStylesType;
   rootClassName?: string;
@@ -87,6 +91,7 @@ export interface PanelProps {
 export interface InternalPanelProps extends PanelProps {
   className?: string;
   prefixCls?: string;
+  supportMotion?: boolean;
 }
 
 export interface UseResizeProps extends Pick<SplitterProps, 'onResize'> {

components/splitter/style/index.ts

@@ -374,6 +374,18 @@ const genSplitterStyle: GenerateStyle<SplitterToken> = (token: SplitterToken): C
         [`&:has(${componentCls}:only-child)`]: {
           overflow: 'hidden',
         },
+
+        '&-transition': {
+          transition: `flex-basis ${token.motionDurationSlow} ${token.motionEaseInOut}`,
+        },
+      },
+
+      '@media (prefers-reduced-motion: reduce)': {
+        [splitPanelCls]: {
+          '&-transition': {
+            transition: 'none',
+          },
+        },
       },
     },
   };

components/theme/interface/components.ts

@@ -49,6 +49,7 @@ import type { ComponentToken as SelectComponentToken } from '../../select/style'
 import type { ComponentToken as SkeletonComponentToken } from '../../skeleton/style';
 import type { ComponentToken as SliderComponentToken } from '../../slider/style';
 import type { ComponentToken as SpaceComponentToken } from '../../space/style';
+import type { ComponentToken as AddonComponentToken } from '../../space/style/addon';
 import type { ComponentToken as SpinComponentToken } from '../../spin/style';
 import type { ComponentToken as SplitterComponentToken } from '../../splitter/style';
 import type { ComponentToken as StatisticComponentToken } from '../../statistic/style';
@@ -68,6 +69,7 @@ import type { ComponentToken as UploadComponentToken } from '../../upload/style'
 
 export interface ComponentTokenMap {
   Affix?: AffixComponentToken;
+  Addon?: AddonComponentToken;
   Alert?: AlertComponentToken;
   Anchor?: AnchorComponentToken;
   Avatar?: AvatarComponentToken;