feat(Dropdown): add clearable prop (#885)

* feat(Dropdown): add `clearable` prop

* update steps

* add toc

* fix focusing

* fix `handleClear` method

* extract styles

* use ShorthandCollection

* add changelog entry

* use overrideProps

Author: layershifter

.github/test-a-feature.md

@@ -17,6 +17,14 @@ Test a feature
     - [Important mentions:](#important-mentions)
   - [Run Screener tests](#run-screener-tests)
     - [Local run command](#local-run-command)
+- [Behavior tets](#behavior-tets)
+  - [Adding test(s)](#adding-tests)
+  - [Running test(s)](#running-tests)
+  - [Troubleshooting](#troubleshooting)
+    - [I am not sure if my line under `@specification` was process correctly](#i-am-not-sure-if-my-line-under-specification-was-process-correctly)
+    - [I am not sure if my line was executed](#i-am-not-sure-if-my-line-was-executed)
+    - [I want to add any description which should not be consider as unit test](#i-want-to-add-any-description-which-should-not-be-consider-as-unit-test)
+    - [I want to create unit tests in separate file not through the regex](#i-want-to-create-unit-tests-in-separate-file-not-through-the-regex)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 

CHANGELOG.md

@@ -20,6 +20,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Features
 - Export `arrow-up`,`arrow-down` and `chat` SVG icon @VyshnaviDasari ([#873](https://github.com/stardust-ui/react/pull/873))
 - Export `FocusZone`'s utilities @sophieH29 ([#876](https://github.com/stardust-ui/react/pull/876))
+- Add `clearable` prop for `Dropdown` @layershifter ([#885](https://github.com/stardust-ui/react/pull/885))
 
 ### Fixes
 - Properly handle falsy values provided as `Flex` and `Flex.Item` children @kuzhelov ([#890](https://github.com/stardust-ui/react/pull/890))

docs/src/examples/components/Dropdown/Types/DropdownExampleClearable.shorthand.steps.ts

@@ -0,0 +1,15 @@
+import { Dropdown } from '@stardust-ui/react'
+
+const selectors = {
+  clearIndicator: `.${Dropdown.slotClassNames.clearIndicator}`,
+  triggerButton: `.${Dropdown.slotClassNames.triggerButton}`,
+  item: (itemIndex: number) => `.${Dropdown.slotClassNames.itemsList} li:nth-child(${itemIndex})`,
+}
+
+const steps = [
+  steps => steps.click(selectors.triggerButton).snapshot('Shows list'),
+  steps => steps.click(selectors.item(3)).snapshot('Selects an item'),
+  steps => steps.click(selectors.clearIndicator).snapshot('Clears the value'),
+]
+
+export default steps

docs/src/examples/components/Dropdown/Types/DropdownExampleClearable.shorthand.tsx

@@ -0,0 +1,20 @@
+import { Dropdown } from '@stardust-ui/react'
+import * as React from 'react'
+
+const inputItems = [
+  'Bruce Wayne',
+  'Natasha Romanoff',
+  'Steven Strange',
+  'Alfred Pennyworth',
+  `Scarlett O'Hara`,
+  'Imperator Furiosa',
+  'Bruce Banner',
+  'Peter Parker',
+  'Selina Kyle',
+]
+
+const DropdownClearableExample = () => (
+  <Dropdown clearable items={inputItems} placeholder="Select your hero" />
+)
+
+export default DropdownClearableExample

docs/src/examples/components/Dropdown/Types/index.tsx

@@ -24,6 +24,11 @@ const Types = () => (
       description="A dropdown can be searchable and allow a multiple selection."
       examplePath="components/Dropdown/Types/DropdownExampleSearchMultiple"
     />
+    <ComponentExample
+      title="Clearable"
+      description="A dropdown can be clearable and let users remove their selection."
+      examplePath="components/Dropdown/Types/DropdownExampleClearable"
+    />
     <ComponentExample
       title="Inline"
       description="A dropdown can be used inline with text."

packages/react/src/components/Dropdown/Dropdown.tsx

@@ -8,6 +8,7 @@ import {
   ShorthandRenderFunction,
   ShorthandValue,
   ComponentEventHandler,
+  ShorthandCollection,
 } from '../../types'
 import { ComponentSlotStylesInput, ComponentVariablesInput } from '../../themes/types'
 import Downshift, {
@@ -29,7 +30,7 @@ import {
   UIComponentProps,
 } from '../../lib'
 import keyboardKey from 'keyboard-key'
-import Indicator from '../Indicator/Indicator'
+import Indicator, { IndicatorProps } from '../Indicator/Indicator'
 import List from '../List/List'
 import Ref from '../Ref/Ref'
 import DropdownItem from './DropdownItem'
@@ -38,9 +39,11 @@ import DropdownSearchInput, { DropdownSearchInputProps } from './DropdownSearchI
 import Button from '../Button/Button'
 import { screenReaderContainerStyles } from '../../lib/accessibility/Styles/accessibilityStyles'
 import ListItem from '../List/ListItem'
+import Icon, { IconProps } from '../Icon/Icon'
 
 export interface DropdownSlotClassNames {
   container: string
+  clearIndicator: string
   triggerButton: string
   itemsList: string
   selectedItems: string
@@ -50,14 +53,20 @@ export interface DropdownProps extends UIComponentProps<DropdownProps, DropdownS
   /** The index of the currently active selected item, if dropdown has a multiple selection. */
   activeSelectedIndex?: number
 
+  /** A dropdown can be clearable and let users remove their selection. */
+  clearable?: boolean
+
+  /** A slot for a clearing indicator. */
+  clearIndicator?: ShorthandValue
+
   /** The initial value for the index of the currently active selected item, in a multiple selection. */
   defaultActiveSelectedIndex?: number
 
   /** The initial value for the search query, if the dropdown is also a search. */
   defaultSearchQuery?: string
 
   /** The initial value or value array, if the array has multiple selection. */
-  defaultValue?: ShorthandValue | ShorthandValue[]
+  defaultValue?: ShorthandValue | ShorthandCollection
 
   /** A dropdown can take the width of its container. */
   fluid?: boolean
@@ -86,7 +95,7 @@ export interface DropdownProps extends UIComponentProps<DropdownProps, DropdownS
   inline?: boolean
 
   /** Array of props for generating list options (Dropdown.Item[]) and selected item labels(Dropdown.SelectedItem[]), if it's a multiple selection. */
-  items?: ShorthandValue[]
+  items?: ShorthandCollection
 
   /**
    * Function to be passed to create string from selected item, if it's a shorthand object. Used when dropdown also has a search function.
@@ -141,7 +150,7 @@ export interface DropdownProps extends UIComponentProps<DropdownProps, DropdownS
   renderSelectedItem?: ShorthandRenderFunction
 
   /** A dropdown can have a search field instead of trigger button. Can receive a custom search function that will replace the default equivalent. */
-  search?: boolean | ((items: ShorthandValue[], searchQuery: string) => ShorthandValue[])
+  search?: boolean | ((items: ShorthandCollection, searchQuery: string) => ShorthandCollection)
 
   /** Component for the search input query. */
   searchInput?: ShorthandValue
@@ -156,7 +165,7 @@ export interface DropdownProps extends UIComponentProps<DropdownProps, DropdownS
   triggerButton?: ShorthandValue
 
   /** Sets currently selected value(s) (controlled mode). */
-  value?: ShorthandValue | ShorthandValue[]
+  value?: ShorthandValue | ShorthandCollection
 }
 
 export interface DropdownState {
@@ -165,7 +174,7 @@ export interface DropdownState {
   focused: boolean
   isOpen?: boolean
   searchQuery?: string
-  value: ShorthandValue | ShorthandValue[]
+  value: ShorthandValue | ShorthandCollection
 }
 
 /**
@@ -192,6 +201,8 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
       content: false,
     }),
     activeSelectedIndex: PropTypes.number,
+    clearable: PropTypes.bool,
+    clearIndicator: customPropTypes.itemShorthand,
     defaultActiveSelectedIndex: PropTypes.number,
     defaultSearchQuery: PropTypes.string,
     defaultValue: PropTypes.oneOfType([
@@ -226,6 +237,7 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
 
   static defaultProps: DropdownProps = {
     as: 'div',
+    clearIndicator: 'close',
     itemToString: item => {
       if (!item || React.isValidElement(item)) {
         return ''
@@ -263,8 +275,16 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
     unhandledProps,
     rtl,
   }: RenderResultConfig<DropdownProps>) {
-    const { search, multiple, getA11yStatusMessage, itemToString, toggleIndicator } = this.props
-    const { defaultHighlightedIndex, searchQuery } = this.state
+    const {
+      clearable,
+      clearIndicator,
+      search,
+      multiple,
+      getA11yStatusMessage,
+      itemToString,
+      toggleIndicator,
+    } = this.props
+    const { defaultHighlightedIndex, searchQuery, value } = this.state
 
     return (
       <ElementType className={classes.root} {...unhandledProps}>
@@ -293,6 +313,8 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
               { refKey: 'innerRef' },
               { suppressRefError: true },
             )
+            const showClearIndicator = clearable && !this.isValueEmpty(value)
+
             return (
               <Ref innerRef={innerRef}>
                 <div
@@ -315,13 +337,32 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
                         )
                       : this.renderTriggerButton(styles, rtl, getToggleButtonProps)}
                   </div>
-                  {Indicator.create(toggleIndicator, {
-                    defaultProps: {
-                      direction: isOpen ? 'top' : 'bottom',
-                      onClick: getToggleButtonProps().onClick,
-                      styles: styles.toggleIndicator,
-                    },
-                  })}
+                  {showClearIndicator
+                    ? Icon.create(clearIndicator, {
+                        defaultProps: {
+                          className: Dropdown.slotClassNames.clearIndicator,
+                          styles: styles.clearIndicator,
+                          xSpacing: 'none',
+                        },
+                        overrideProps: (predefinedProps: IconProps) => ({
+                          onClick: (e, iconProps: IconProps) => {
+                            _.invoke(predefinedProps, 'onClick', e, iconProps)
+                            this.handleClear()
+                          },
+                        }),
+                      })
+                    : Indicator.create(toggleIndicator, {
+                        defaultProps: {
+                          direction: isOpen ? 'top' : 'bottom',
+                          styles: styles.toggleIndicator,
+                        },
+                        overrideProps: (predefinedProps: IndicatorProps) => ({
+                          onClick: (e, indicatorProps: IndicatorProps) => {
+                            _.invoke(predefinedProps, 'onClick', e, indicatorProps)
+                            getToggleButtonProps().onClick(e)
+                          },
+                        }),
+                      })}
                   {this.renderItemsList(
                     styles,
                     variables,
@@ -392,7 +433,7 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
     const { searchQuery, value } = this.state
 
     const noPlaceholder =
-      searchQuery.length > 0 || (multiple && (value as ShorthandValue[]).length > 0)
+      searchQuery.length > 0 || (multiple && (value as ShorthandCollection).length > 0)
 
     return DropdownSearchInput.create(searchInput || {}, {
       defaultProps: {
@@ -510,7 +551,7 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
 
   private renderSelectedItems(variables, rtl: boolean) {
     const { renderSelectedItem } = this.props
-    const value = this.state.value as ShorthandValue[]
+    const value = this.state.value as ShorthandCollection
 
     if (value.length === 0) {
       return null
@@ -570,10 +611,10 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
     }
   }
 
-  private getItemsFilteredBySearchQuery = (): ShorthandValue[] => {
+  private getItemsFilteredBySearchQuery = (): ShorthandCollection => {
     const { items, itemToString, multiple, search } = this.props
     const { searchQuery, value } = this.state
-    const filteredItems = multiple ? _.difference(items, value as ShorthandValue[]) : items
+    const filteredItems = multiple ? _.difference(items, value as ShorthandCollection) : items
 
     if (search) {
       if (_.isFunction(search)) {
@@ -627,7 +668,7 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
       this.handleSelectedItemRemove(e, item, predefinedProps, DropdownSelectedItemProps)
     },
     onClick: (e: React.SyntheticEvent, DropdownSelectedItemProps: DropdownSelectedItemProps) => {
-      const { value } = this.state as { value: ShorthandValue[] }
+      const { value } = this.state as { value: ShorthandCollection }
       this.trySetState({
         activeSelectedIndex: value.indexOf(item),
       })
@@ -729,7 +770,7 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
     ) {
       return
     }
-    const { value } = this.state as { value: ShorthandValue[] }
+    const { value } = this.state as { value: ShorthandCollection }
     if (value.length > 0) {
       this.trySetState({ activeSelectedIndex: value.length - 1 })
     }
@@ -742,12 +783,21 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
     if (
       multiple &&
       (searchQuery === '' || this.inputRef.current.selectionStart === 0) &&
-      (value as ShorthandValue[]).length > 0
+      (value as ShorthandCollection).length > 0
     ) {
       this.removeItemFromValue()
     }
   }
 
+  private handleClear = () => {
+    const initialState = this.getInitialAutoControlledState(this.props)
+
+    this.setState({ value: initialState.value })
+
+    this.tryFocusSearchInput()
+    this.tryFocusTriggerButton()
+  }
+
   private handleContainerClick = () => {
     this.tryFocusSearchInput()
   }
@@ -797,7 +847,7 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
   private handleSelectedChange = (item: ShorthandValue) => {
     const { items, multiple, getA11ySelectionMessage } = this.props
     const newState = {
-      value: multiple ? [...(this.state.value as ShorthandValue[]), item] : item,
+      value: multiple ? [...(this.state.value as ShorthandCollection), item] : item,
       searchQuery: this.getSelectedItemAsString(item),
     }
 
@@ -834,7 +884,7 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
   ) {
     const { activeSelectedIndex, value } = this.state as {
       activeSelectedIndex: number
-      value: ShorthandValue[]
+      value: ShorthandCollection
     }
     const previousKey = rtl ? keyboardKey.ArrowRight : keyboardKey.ArrowLeft
     const nextKey = rtl ? keyboardKey.ArrowLeft : keyboardKey.ArrowRight
@@ -894,7 +944,7 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
 
   private removeItemFromValue(item?: ShorthandValue) {
     const { getA11ySelectionMessage } = this.props
-    let value = this.state.value as ShorthandValue[]
+    let value = this.state.value as ShorthandCollection
     let poppedItem = item
 
     if (poppedItem) {
@@ -932,9 +982,8 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
    */
   private getSelectedItemAsString = (value: ShorthandValue): string => {
     const { itemToString, multiple, placeholder } = this.props
-    const isValueEmpty = _.isArray(value) ? value.length < 1 : !value
 
-    if (isValueEmpty) {
+    if (this.isValueEmpty(value)) {
       return placeholder
     }
 
@@ -944,10 +993,15 @@ class Dropdown extends AutoControlledComponent<Extendable<DropdownProps>, Dropdo
 
     return itemToString(value)
   }
+
+  private isValueEmpty = (value: ShorthandValue | ShorthandCollection) => {
+    return _.isArray(value) ? value.length < 1 : !value
+  }
 }
 
 Dropdown.slotClassNames = {
   container: `${Dropdown.className}__container`,
+  clearIndicator: `${Dropdown.className}__clear-indicator`,
   triggerButton: `${Dropdown.className}__trigger-button`,
   itemsList: `${Dropdown.className}__items-list`,
   selectedItems: `${Dropdown.className}__selected-items`,