From e71eb3de7e44a6309a4346e4c29a7f1c067b5cba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=AB=98=E8=89=B3=E5=85=B5?= <yanbing.gao@aliyun.com>
Date: Tue, 13 Oct 2026 15:41:48 +0800
Subject: [PATCH] feat: unify allowClear configuration

---
 README.md                     | 17 +++++++
 package.json                  |  2 +-
 src/BaseSelect/index.tsx      |  6 ++-
 src/SelectInput/index.tsx     |  3 ++
 src/hooks/useAllowClear.tsx   | 26 +++++------
 src/utils/warningPropsUtil.ts |  6 ++-
 tests/allowClear.test.tsx     | 86 +++++++++++++++++++++++++++++++++++
 7 files changed, 127 insertions(+), 19 deletions(-)
 create mode 100644 tests/allowClear.test.tsx

diff --git a/README.md b/README.md
index 6da84ebf..0363bd2e 100644
--- a/README.md
+++ b/README.md
@@ -167,3 +167,20 @@ The release flow is handled by `@rc-component/np` through the `rc-np` command af
 ## License
 
 @rc-component/select is released under the [MIT](./LICENSE) license.
+
+### Clear configuration
+
+`allowClear` accepts a boolean or an `AllowClearConfig` object from `@rc-component/util`:
+
+```ts
+interface AllowClearConfig {
+  clearIcon?: React.ReactNode;
+  disabled?: boolean;
+  tabIndex?: number;
+  label?: string;
+}
+```
+
+All fields are optional. `disabled: true` behaves like `allowClear={false}`: the clear button and space reserved solely for it are removed; the input remains editable. Existing suffixes and other content are preserved. This changes the previous hidden-button spacing behavior where applicable.
+
+`tabIndex` affects only the clear button; `-1` removes it from Tab navigation while retaining mouse activation. `label` supplies its accessible name through `aria-label`. Defaults, clear values, callbacks, and component state restrictions are unchanged.
diff --git a/package.json b/package.json
index 14b6d995..cb18d197 100644
--- a/package.json
+++ b/package.json
@@ -50,7 +50,7 @@
   "dependencies": {
     "@rc-component/overflow": "^1.0.0",
     "@rc-component/trigger": "^3.0.0",
-    "@rc-component/util": "^1.13.0",
+    "@rc-component/util": "^1.14.0",
     "@rc-component/virtual-list": "^1.2.0",
     "clsx": "^2.1.1"
   },
diff --git a/src/BaseSelect/index.tsx b/src/BaseSelect/index.tsx
index 0389f623..c2dea864 100644
--- a/src/BaseSelect/index.tsx
+++ b/src/BaseSelect/index.tsx
@@ -1,6 +1,6 @@
 import type { AlignType, BuildInPlacements } from '@rc-component/trigger';
 import { clsx } from 'clsx';
-import { getDOM, isNonNullable, useEvent } from '@rc-component/util';
+import { type AllowClearConfig, getDOM, isNonNullable, useEvent } from '@rc-component/util';
 import type { ScrollConfig, ScrollTo } from '@rc-component/virtual-list';
 import * as React from 'react';
 import { useAllowClear } from '../hooks/useAllowClear';
@@ -185,7 +185,7 @@ export interface BaseSelectProps
   tokenSeparators?: string[] | ((input: string) => string[]);
 
   // >>> Icons
-  allowClear?: boolean | { clearIcon?: React.ReactNode; label?: string };
+  allowClear?: boolean | AllowClearConfig;
   prefix?: React.ReactNode;
   /** @deprecated Please use `suffix` instead. */
   suffixIcon?: RenderNode;
@@ -725,6 +725,7 @@ const BaseSelect = React.forwardRef<BaseSelectRef, BaseSelectProps>((props, ref)
     allowClear: mergedAllowClear,
     clearIcon: clearNode,
     label: clearLabel,
+    tabIndex: clearTabIndex,
   } = useAllowClear(
     prefixCls,
     displayValues,
@@ -768,6 +769,7 @@ const BaseSelect = React.forwardRef<BaseSelectRef, BaseSelectProps>((props, ref)
       suffix={mergedSuffixIcon}
       clearIcon={clearNode}
       clearLabel={clearLabel}
+      clearTabIndex={clearTabIndex}
       // Type or mode
       multiple={multiple}
       mode={mode}
diff --git a/src/SelectInput/index.tsx b/src/SelectInput/index.tsx
index 0035803a..55da4919 100644
--- a/src/SelectInput/index.tsx
+++ b/src/SelectInput/index.tsx
@@ -29,6 +29,7 @@ export interface SelectInputProps extends Omit<React.HTMLAttributes<HTMLDivEleme
   suffix?: React.ReactNode;
   clearIcon?: React.ReactNode;
   clearLabel?: string;
+  clearTabIndex?: number;
   removeIcon?: RenderNode;
   multiple?: boolean;
   displayValues: DisplayValueType[];
@@ -89,6 +90,7 @@ export default React.forwardRef<SelectInputRef, SelectInputProps>(function Selec
     suffix,
     clearIcon,
     clearLabel,
+    clearTabIndex,
     children,
 
     // Data
@@ -310,6 +312,7 @@ export default React.forwardRef<SelectInputRef, SelectInputProps>(function Selec
           <button
             type="button"
             aria-label={clearLabel}
+            tabIndex={clearTabIndex}
             className={clsx(`${prefixCls}-clear`, classNames?.clear)}
             style={styles?.clear}
             onMouseDown={(e) => {
diff --git a/src/hooks/useAllowClear.tsx b/src/hooks/useAllowClear.tsx
index d94e5b33..cc237d5e 100644
--- a/src/hooks/useAllowClear.tsx
+++ b/src/hooks/useAllowClear.tsx
@@ -1,9 +1,13 @@
 import type { DisplayValueType, Mode } from '../interface';
 import type React from 'react';
-import { isReactRenderable } from '@rc-component/util';
+import {
+  type AllowClearConfig,
+  isReactRenderable,
+  useAllowClear as useClearConfig,
+} from '@rc-component/util';
 import { useMemo } from 'react';
 
-export interface AllowClearConfig {
+interface ClearInfo extends AllowClearConfig {
   allowClear: boolean;
   clearIcon: React.ReactNode;
   label: string;
@@ -12,31 +16,23 @@ export interface AllowClearConfig {
 export const useAllowClear = (
   prefixCls: string,
   displayValues: DisplayValueType[],
-  allowClear?: boolean | { clearIcon?: React.ReactNode; label?: string },
+  allowClear?: boolean | AllowClearConfig,
   clearIcon?: React.ReactNode,
   disabled: boolean = false,
   mergedSearchValue?: string,
   mode?: Mode,
-): AllowClearConfig => {
-  // Convert boolean to object first
-  const allowClearConfig = useMemo<Partial<AllowClearConfig>>(() => {
-    if (typeof allowClear === 'boolean') {
-      return { allowClear };
-    }
-    if (allowClear && typeof allowClear === 'object') {
-      return allowClear;
-    }
-    return { allowClear: false };
-  }, [allowClear]);
+): ClearInfo => {
+  const allowClearConfig = useClearConfig(allowClear);
 
   return useMemo(() => {
     const mergedAllowClear =
       !disabled &&
-      allowClearConfig.allowClear !== false &&
+      !allowClearConfig.disabled &&
       (displayValues.length || mergedSearchValue) &&
       !(mode === 'combobox' && mergedSearchValue === '');
 
     return {
+      ...allowClearConfig,
       allowClear: mergedAllowClear,
       clearIcon: mergedAllowClear
         ? isReactRenderable(allowClearConfig.clearIcon)
diff --git a/src/utils/warningPropsUtil.ts b/src/utils/warningPropsUtil.ts
index e6f96ae3..6edf86fc 100644
--- a/src/utils/warningPropsUtil.ts
+++ b/src/utils/warningPropsUtil.ts
@@ -74,7 +74,11 @@ function warningProps(props: SelectProps) {
 
   // Customize `getInputElement` should not use `allowClear` & `placeholder`
   noteOnce(
-    mode !== 'combobox' || !getInputElement || !allowClear || !placeholder,
+    mode !== 'combobox' ||
+      !getInputElement ||
+      !allowClear ||
+      (typeof allowClear === 'object' && allowClear.disabled) ||
+      !placeholder,
     'Customize `getInputElement` should customize clear and placeholder logic instead of configuring `allowClear` and `placeholder`.',
   );
 
diff --git a/tests/allowClear.test.tsx b/tests/allowClear.test.tsx
new file mode 100644
index 00000000..08a27053
--- /dev/null
+++ b/tests/allowClear.test.tsx
@@ -0,0 +1,86 @@
+import { fireEvent, render } from '@testing-library/react';
+import * as React from 'react';
+import Select from '../src';
+import { resetWarned } from '@rc-component/util';
+
+describe.each([undefined, 'multiple', 'tags', 'combobox'] as const)(
+  'allowClear mode=%s',
+  (mode) => {
+    it('disables the clear entry and restores the complete configuration', () => {
+      const onClear = jest.fn();
+      const onChange = jest.fn();
+      const props = {
+        mode,
+        defaultValue: 'one',
+        onClear,
+        onChange,
+        options: [{ value: 'one' }],
+        suffix: 'suffix',
+      };
+      const config = Object.freeze({ clearIcon: 'custom', label: 'Erase', tabIndex: -1 });
+      const { container, getByRole, queryByRole, rerender } = render(
+        <Select {...props} allowClear={false} />,
+      );
+      const markup = container.innerHTML;
+      rerender(<Select {...props} allowClear={{ ...config, disabled: true }} />);
+      expect(container.innerHTML).toBe(markup);
+      expect(queryByRole('button', { name: 'Erase' })).toBeNull();
+      expect(onClear).not.toHaveBeenCalled();
+      expect(onChange).not.toHaveBeenCalled();
+      expect(container.querySelector('.rc-select-suffix')).toHaveTextContent('suffix');
+
+      rerender(<Select {...props} allowClear={config} />);
+      const button = getByRole('button', { name: 'Erase' });
+      expect(button).toHaveTextContent('custom');
+      expect(button.tabIndex).toBe(-1);
+      fireEvent.click(button);
+      expect(onClear).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(
+        mode === 'multiple' || mode === 'tags' ? [] : undefined,
+        mode === 'multiple' || mode === 'tags' ? [] : undefined,
+      );
+      expect(queryByRole('button', { name: 'Erase' })).toBeNull();
+    });
+  },
+);
+
+it('does not override component disabled or empty-value restrictions', () => {
+  const { queryByRole, rerender } = render(
+    <Select value="one" disabled allowClear={{ disabled: false }} />,
+  );
+  expect(queryByRole('button', { name: 'Clear' })).toBeNull();
+  rerender(<Select allowClear={{ disabled: false }} />);
+  expect(queryByRole('button', { name: 'Clear' })).toBeNull();
+});
+
+it('updates the clear tabIndex without changing the input tabIndex', () => {
+  const { getByRole, rerender } = render(
+    <Select value="one" tabIndex={3} allowClear={{ tabIndex: -1 }} />,
+  );
+  expect(getByRole('button', { name: 'Clear' }).tabIndex).toBe(-1);
+  expect(getByRole('combobox').tabIndex).toBe(3);
+  rerender(<Select value="one" tabIndex={3} allowClear={{ tabIndex: 0, label: 'Erase' }} />);
+  expect(getByRole('button', { name: 'Erase' }).tabIndex).toBe(0);
+  expect(getByRole('combobox').tabIndex).toBe(3);
+});
+
+it('treats a disabled clear configuration as false in custom-input warnings', () => {
+  resetWarned();
+  const warning = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  try {
+    const props = {
+      mode: 'combobox' as const,
+      getInputElement: () => <input />,
+      placeholder: 'Search',
+    };
+    const { rerender } = render(<Select {...props} allowClear={{ disabled: true }} />);
+    expect(warning).not.toHaveBeenCalled();
+    rerender(<Select {...props} allowClear />);
+    expect(warning).toHaveBeenCalledWith(
+      expect.stringContaining('Customize \x60getInputElement\x60 should customize clear'),
+    );
+  } finally {
+    warning.mockRestore();
+    resetWarned();
+  }
+});