feat(TextArea): add clearable functionality to TextArea component (#7021)

src/components/config-provider/config-provider.tsx

@@ -42,6 +42,9 @@ type Config = {
   searchBar?: {
     searchIcon?: ReactNode
   }
+  textArea?: {
+    clearIcon?: ReactNode
+  }
 }
 
 export const defaultConfigRef: {

src/components/text-area/demos/demo1.tsx

@@ -1,6 +1,6 @@
-import React, { useState } from 'react'
 import { TextArea } from 'antd-mobile'
 import { DemoBlock } from 'demos'
+import React, { useState } from 'react'
 
 export default () => {
   const [value, setValue] = useState('')
@@ -20,13 +20,25 @@ export default () => {
         <TextArea placeholder='请输入内容' rows={5} />
       </DemoBlock>
 
+      <DemoBlock title='带清除按钮'>
+        <TextArea placeholder='请输入内容' clearable />
+      </DemoBlock>
+
       <DemoBlock title='根据内容自动调整高度'>
         <TextArea
           placeholder='请输入内容'
           autoSize={{ minRows: 3, maxRows: 5 }}
         />
       </DemoBlock>
 
+      <DemoBlock title='带清除按钮的自动调整高度'>
+        <TextArea
+          placeholder='请输入内容'
+          autoSize={{ minRows: 3, maxRows: 5 }}
+          clearable
+        />
+      </DemoBlock>
+
       <DemoBlock title='字数统计'>
         <TextArea defaultValue={'北极星垂地，\n东山月满川。'} showCount />
       </DemoBlock>

src/components/text-area/index.en.md

@@ -17,16 +17,19 @@ Long text input that requires wrapping.
 | Name | Description | Type | Default |
 | --- | --- | --- | --- |
 | autoSize | Adaptive content height | `boolean \| { minRows?: number, maxRows?: number }` | `false` |
+| clearable | Whether to enable the clear icon, the input box will be cleared after clicking the clear icon | `boolean` | `false` |
+| clearIcon | Custom clear icon | `ReactNode` | `<CloseCircleFill />` |
 | defaultValue | Input value by default | `string` | - |
 | id | `id` of `textarea` element, often used in conjunction with `label` | `string` | - |
 | maxLength | Maximum number of characters | `number` | - |
 | onChange | Triggered when the TextArea content changed | `(value: string) => void` | - |
+| onClear | Triggered after clicking the clear button | `() => void` | - |
 | placeholder | Hint text | `string` | - |
 | rows | Number of rows | `number` | `2` |
 | showCount | Display the number of words, supports custom render | `boolean \| ((length: number, maxLength?: number) => ReactNode)` | `false` |
 | value | Input value | `string` | - |
 
-In addition, the following native attributes are supported: `autoComplete` `autoFocus` `disabled` `readOnly` `onFocus` `onBlur` `onCompositionStart` `onCompositionEnd` `onClick`
+In addition, the following native attributes are supported: `autoComplete` `autoFocus` `disabled` `readOnly` `onFocus` `onBlur` `onCompositionStart` `onCompositionEnd` `onClick` `onKeyDown` `enterKeyHint`
 
 ### CSS Variables
 

src/components/text-area/index.zh.md

@@ -17,16 +17,19 @@
 | 属性 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |
 | autoSize | 自适应内容高度 | `boolean \| { minRows?: number, maxRows?: number }` | `false` |
+| clearable | 是否启用清除图标，点击清除图标后会清空输入框 | `boolean` | `false` |
+| clearIcon | 自定义清除图标 | `ReactNode` | `<CloseCircleFill />` |
 | defaultValue | 默认值 | `string` | - |
 | id | `textarea` 元素的 `id`，常用来配合 `label` 使用 | `string` | - |
 | maxLength | 最大字符数 | `number` | - |
 | onChange | 文本域内容变化时触发 | `(value: string) => void` | - |
+| onClear | 点击清除按钮后触发 | `() => void` | - |
 | placeholder | 提示文本 | `string` | - |
 | rows | 行数 | `number` | `2` |
 | showCount | 显示字数，支持自定义渲染 | `boolean \| ((length: number, maxLength?: number) => ReactNode)` | `false` |
 | value | 输入值 | `string` | - |
 
-此外还支持以下原生属性：`autoComplete` `autoFocus` `disabled` `readOnly` `onFocus` `onBlur` `onCompositionStart` `onCompositionEnd` `onClick`
+此外还支持以下原生属性：`autoComplete` `autoFocus` `disabled` `readOnly` `onFocus` `onBlur` `onCompositionStart` `onCompositionEnd` `onClick` `onKeyDown` `enterKeyHint`
 
 ### CSS 变量
 

src/components/text-area/tests/text-area.test.tsx

@@ -1,6 +1,8 @@
 import React, { createRef } from 'react'
-import { render, fireEvent, act } from 'testing'
+import { act, fireEvent, render, screen } from 'testing'
 import TextArea, { TextAreaRef } from '..'
+import * as validate from '../../../utils/validate'
+import ConfigProvider from '../../config-provider'
 
 const classPrefix = 'adm-text-area'
 const lineHeight = 25
@@ -165,4 +167,113 @@ describe('TextArea', () => {
     expect(onEnterPress).toBeCalledTimes(2)
     fireEvent.keyUp(textarea, { keyCode: 14 })
   })
+
+  test('the clear button should works', async () => {
+    const { container } = render(
+      <TextArea clearable defaultValue={'testValue'} />
+    )
+    const textarea = screen.getByRole('textbox') as HTMLTextAreaElement
+    const clearBtn = container.querySelector(`.${classPrefix}-clear`)
+    expect(clearBtn).toBeInTheDocument()
+    fireEvent.click(clearBtn as HTMLElement)
+    expect(textarea.value).toBe('')
+  })
+
+  test('should works with composition on iOS', async () => {
+    const spy = jest.spyOn(validate, 'isIOS').mockReturnValue(true)
+    const onCompositionStart = jest.fn()
+    const onCompositionEnd = jest.fn()
+    const { container } = render(
+      <TextArea
+        clearable
+        defaultValue={'testValue'}
+        onCompositionStart={onCompositionStart}
+        onCompositionEnd={onCompositionEnd}
+      />
+    )
+    const textarea = screen.getByRole('textbox') as HTMLTextAreaElement
+    act(() => {
+      textarea.focus()
+    })
+    expect(textarea).toHaveFocus()
+    fireEvent.compositionStart(textarea)
+    expect(onCompositionStart).toBeCalledTimes(1)
+    fireEvent.compositionEnd(textarea)
+    expect(onCompositionEnd).toBeCalledTimes(1)
+    fireEvent.compositionStart(textarea)
+    expect(onCompositionStart).toBeCalledTimes(2)
+
+    const clearBtn = container.querySelector(
+      `.${classPrefix}-clear`
+    ) as HTMLElement
+    expect(clearBtn).toBeInTheDocument()
+    fireEvent.click(clearBtn)
+    expect(textarea).not.toHaveFocus()
+    spy.mockRestore()
+  })
+
+  test('should not blur on non-iOS when click clear button', async () => {
+    const spy = jest.spyOn(validate, 'isIOS').mockReturnValue(false)
+    const { container } = render(
+      <TextArea clearable defaultValue={'testValue'} />
+    )
+    const textarea = screen.getByRole('textbox') as HTMLTextAreaElement
+    act(() => {
+      textarea.focus()
+    })
+    fireEvent.compositionStart(textarea)
+    expect(textarea).toHaveFocus()
+
+    const clearBtn = container.querySelector(
+      `.${classPrefix}-clear`
+    ) as HTMLElement
+    fireEvent.click(clearBtn)
+    // On non-iOS, the textarea should keep focus even during composition
+    expect(textarea).toHaveFocus()
+    expect(textarea.value).toBe('')
+    spy.mockRestore()
+  })
+
+  test('onClear callback', () => {
+    const onClear = jest.fn()
+    const { container } = render(
+      <TextArea clearable defaultValue={'testValue'} onClear={onClear} />
+    )
+    const textarea = screen.getByRole('textbox') as HTMLTextAreaElement
+    fireEvent.focus(textarea)
+    const clearBtn = container.querySelector(`.${classPrefix}-clear`)
+    fireEvent.click(clearBtn as HTMLElement)
+    expect(onClear).toBeCalledTimes(1)
+    expect(textarea.value).toBe('')
+  })
+
+  describe('clearIcon', () => {
+    it('default', () => {
+      const { baseElement } = render(<TextArea value='foobar' clearable />)
+      expect(baseElement.querySelector('.antd-mobile-icon')).toBeTruthy()
+    })
+
+    it('props', () => {
+      render(<TextArea value='foobar' clearable clearIcon='bamboo' />)
+      expect(screen.getByText('bamboo')).toBeVisible()
+    })
+
+    it('context', () => {
+      render(
+        <ConfigProvider textArea={{ clearIcon: 'little' }}>
+          <TextArea value='foobar' clearable />
+        </ConfigProvider>
+      )
+      expect(screen.getByText('little')).toBeVisible()
+    })
+
+    it('props override context', () => {
+      render(
+        <ConfigProvider textArea={{ clearIcon: 'little' }}>
+          <TextArea value='foobar' clearable clearIcon='bamboo' />
+        </ConfigProvider>
+      )
+      expect(screen.getByText('bamboo')).toBeVisible()
+    })
+  })
 })

src/components/text-area/text-area.less

@@ -6,6 +6,8 @@
   --text-align: left;
   --count-text-align: right;
   position: relative;
+  display: flex;
+  align-items: flex-start;
   width: 100%;
   max-width: 100%;
   max-height: 100%;
@@ -75,3 +77,18 @@
   font-size: var(--adm-font-size-9);
   padding-top: 8px;
 }
+
+.adm-text-area-clear {
+  flex: none;
+  margin-left: 8px;
+  color: var(--adm-color-light);
+  &:active {
+    color: var(--adm-color-weak);
+  }
+  padding: 4px;
+  cursor: pointer;
+  .antd-mobile-icon {
+    display: block;
+    font-size: var(--adm-font-size-7);
+  }
+}

src/components/text-area/text-area.tsx

@@ -1,12 +1,15 @@
 import { useIsomorphicLayoutEffect } from 'ahooks'
+import { CloseCircleFill } from 'antd-mobile-icons'
 import type { ReactNode } from 'react'
 import React, { forwardRef, useImperativeHandle, useRef } from 'react'
 import runes from 'runes2'
 import useInputHandleKeyDown from '../../components/input/useInputHandleKeyDown'
 import { devError } from '../../utils/dev-log'
 import { NativeProps, withNativeProps } from '../../utils/native-props'
 import { usePropsValue } from '../../utils/use-props-value'
+import { isIOS } from '../../utils/validate'
 import { mergeProps } from '../../utils/with-default-props'
+import { useConfig } from '../config-provider'
 
 const classPrefix = 'adm-text-area'
 
@@ -50,6 +53,9 @@ export type TextAreaProps = Pick<
     | 'previous'
     | 'search'
     | 'send'
+  clearable?: boolean
+  clearIcon?: ReactNode
+  onClear?: () => void
 } & NativeProps<
     | '--font-size'
     | '--color'
@@ -71,11 +77,13 @@ const defaultProps = {
   showCount: false as NonNullable<TextAreaProps['showCount']>,
   autoSize: false as NonNullable<TextAreaProps['autoSize']>,
   defaultValue: '',
+  clearIcon: <CloseCircleFill />,
 }
 
 export const TextArea = forwardRef<TextAreaRef, TextAreaProps>(
   (p: TextAreaProps, ref) => {
-    const props = mergeProps(defaultProps, p)
+    const { locale, textArea: componentConfig = {} } = useConfig()
+    const props = mergeProps(defaultProps, componentConfig, p)
     const { autoSize, showCount, maxLength } = props
     const [value, setValue] = usePropsValue({
       ...props,
@@ -137,6 +145,9 @@ export const TextArea = forwardRef<TextAreaRef, TextAreaProps>(
 
     const compositingRef = useRef(false)
 
+    const shouldShowClear =
+      props.clearable && !!value && !props.readOnly && !props.disabled
+
     let count
     const valueLength = runes(value).length
     if (typeof showCount === 'function') {
@@ -201,6 +212,27 @@ export const TextArea = forwardRef<TextAreaRef, TextAreaProps>(
           onKeyDown={handleKeydown}
           enterKeyHint={props.enterKeyHint}
         />
+        {shouldShowClear && (
+          <div
+            className={`${classPrefix}-clear`}
+            onMouseDown={e => {
+              e.preventDefault()
+            }}
+            onClick={() => {
+              setValue('')
+              props.onClear?.()
+
+              // https://github.com/ant-design/ant-design-mobile/issues/5212
+              if (isIOS() && compositingRef.current) {
+                compositingRef.current = false
+                nativeTextAreaRef.current?.blur()
+              }
+            }}
+            aria-label={locale.TextArea.clear}
+          >
+            {props.clearIcon}
+          </div>
+        )}
         {count}
 
         {autoSize && (

src/locales/ar-SA.ts

@@ -111,6 +111,7 @@ const arSA = mergeLocale(base, {
   'Stepper': { 'decrease': 'يقلل', 'increase': 'يزيد' },
   'Switch': { 'name': 'زر الفتح والإغلاق' },
   'Selector': { 'name': 'اختر مجموعة' },
+  'TextArea': { 'clear': 'إزالة' },
 })
 
 export default arSA

src/locales/base.ts

@@ -141,6 +141,9 @@ export const base = {
   Selector: {
     name: 'Selector',
   },
+  TextArea: {
+    clear: 'clear',
+  },
 }
 
 export type Locale = typeof base

src/locales/cnr-ME.ts

@@ -144,6 +144,9 @@ const cnrME = mergeLocale(base, {
   Selector: {
     name: 'Selektor',
   },
+  TextArea: {
+    clear: 'očisti',
+  },
 })
 
 export default cnrME

src/locales/da-DK.ts

@@ -126,6 +126,9 @@ const daDK = mergeLocale(base, {
   Selector: {
     name: 'Vælger',
   },
+  TextArea: {
+    clear: 'ryd',
+  },
 })
 
 export default daDK

src/locales/de-DE.ts

@@ -116,6 +116,7 @@ const deDE = mergeLocale(base, {
   'Stepper': { 'decrease': 'Reduzieren', 'increase': 'Erhöhen' },
   'Switch': { 'name': 'Schalter' },
   'Selector': { 'name': 'Gruppe auswählen' },
+  'TextArea': { 'clear': 'Löschen' },
 })
 
 export default deDE

src/locales/es-ES.ts

@@ -92,6 +92,9 @@ const esES = mergeLocale(base, {
   ImageUploader: {
     uploading: 'Subiendo...',
   },
+  Input: {
+    clear: 'Borrar',
+  },
   Mask: {
     name: 'Máscara',
   },
@@ -106,6 +109,9 @@ const esES = mergeLocale(base, {
     canRelease: 'Suelte para refrescar inmediatamente',
     complete: 'Refrescó exitosamente',
   },
+  TextArea: {
+    clear: 'Borrar',
+  },
 })
 
 export default esES

src/locales/fa-IR.ts

@@ -108,6 +108,9 @@ const faIR = mergeLocale(base, {
   NumberKeyboard: {
     backspace: 'حذف',
   },
+  TextArea: {
+    clear: 'پاک کردن',
+  },
 })
 
 export default faIR