feat(VSelect/VAutocomplete/VCombobox): new events for multi-selection (#23038)

resolves #4054
resolves #5682

Author: J-Sek

packages/api-generator/src/locale/en/VCombobox.json

@@ -10,6 +10,9 @@
   "slots": {
     "item": "Define a custom item appearance. The root element of this slot must be a **v-list-item** with `v-bind=\"props\"` applied. `props` includes everything required for the default select list behaviour - including title, value, click handlers, virtual scrolling, and anything else that has been added with `item-props`."
   },
+  "events": {
+    "item:created": "Emitted when a value is committed that does not match any existing item (free-text create). Also emits **item:added**."
+  },
   "exposed": {
     "selectionIndex": "The index of the currently selected item."
   }

packages/api-generator/src/locale/en/generic.json

@@ -103,6 +103,8 @@
     "click:prependInner": "Emitted when prepended inner icon is clicked.",
     "input": "The updated bound model.",
     "group:selected": "Event that is emitted when an item is selected within a group.",
+    "item:added": "Emitted when an item is added to the model.",
+    "item:removed": "Emitted when an item is removed from the model.",
     "rejected": "Emitted when some of the files from user input, drop or folder selection did not pass through `strict-accept` filter.",
     "update:focused": "Event that is emitted when the component's focus state changes.",
     "update:menu": "Event that is emitted when the component's menu state changes.",

packages/docs/src/data/new-in.json

@@ -22,6 +22,10 @@
     "slots": {
       "menu-header": "3.12.0",
       "menu-footer": "3.12.0"
+    },
+    "events": {
+      "item:added": "3.13.0",
+      "item:removed": "3.13.0"
     }
   },
   "VAvatar": {
@@ -83,6 +87,11 @@
     "slots": {
       "menu-header": "3.12.0",
       "menu-footer": "3.12.0"
+    },
+    "events": {
+      "item:added": "3.13.0",
+      "item:removed": "3.13.0",
+      "item:created": "3.13.0"
     }
   },
   "VConfirmEdit": {
@@ -289,6 +298,10 @@
     "slots": {
       "menu-header": "3.12.0",
       "menu-footer": "3.12.0"
+    },
+    "events": {
+      "item:added": "3.13.0",
+      "item:removed": "3.13.0"
     }
   },
   "VSkeletonLoader": {

packages/vuetify/src/components/VAutocomplete/VAutocomplete.tsx

@@ -119,9 +119,11 @@ export const VAutocomplete = genericComponent<new <
     'update:search': (value: any) => true,
     'update:modelValue': (value: any) => true,
     'update:menu': (value: boolean) => true,
+    'item:added': (item: ListItem) => true,
+    'item:removed': (item: ListItem) => true,
   },
 
-  setup (props, { slots }) {
+  setup (props, { emit, slots }) {
     const { t } = useLocale()
     const vTextFieldRef = ref<VTextField>()
     const isFocused = shallowRef(false)
@@ -368,7 +370,10 @@ export const VAutocomplete = genericComponent<new <
       }
     }
     function onUpdateModelValue (v: any) {
-      if (v == null || (v === '' && !props.multiple && !hasSelectionSlot.value)) model.value = []
+      if (v == null || (v === '' && !props.multiple && !hasSelectionSlot.value)) {
+        for (const item of model.value) emit('item:removed', item)
+        model.value = []
+      }
     }
 
     function onBlur (e: FocusEvent) {
@@ -384,15 +389,19 @@ export const VAutocomplete = genericComponent<new <
     function select (item: ListItem | undefined, set: boolean | null = true) {
       if (!item || item.props.disabled) return
 
+      const comparator = props.valueComparator || deepEqual
+
       if (props.multiple) {
-        const index = model.value.findIndex(selection => (props.valueComparator || deepEqual)(selection.value, item.value))
+        const index = model.value.findIndex(selection => comparator(selection.value, item.value))
         const add = set == null ? !~index : set
 
         if (~index) {
           const value = add ? [...model.value, item] : [...model.value]
-          value.splice(index, 1)
+          const [removed] = value.splice(index, 1)
+          if (!add) emit('item:removed', removed) // skip if only reordered
           model.value = value
         } else if (add) {
+          emit('item:added', item)
           model.value = [...model.value, item]
         }
 
@@ -401,7 +410,21 @@ export const VAutocomplete = genericComponent<new <
         }
       } else {
         const add = set !== false
-        model.value = add ? [item] : []
+        const old = model.value[0]
+
+        if (add) {
+          if (old && !comparator(old.value, item.value)) {
+            emit('item:removed', old)
+            emit('item:added', item)
+          } else if (!old) {
+            emit('item:added', item)
+          }
+          model.value = [item]
+        } else {
+          if (old) emit('item:removed', old)
+          model.value = []
+        }
+
         _searchLock.value = isPristine.value ? '' : (search.value ?? '')
         search.value = add && !hasSelectionSlot.value ? item.title : ''
 
@@ -423,7 +446,10 @@ export const VAutocomplete = genericComponent<new <
 
         nextTick(() => isSelecting.value = false)
       } else {
-        if (!props.multiple && search.value == null) model.value = []
+        if (!props.multiple && search.value == null) {
+          for (const item of model.value) emit('item:removed', item)
+          model.value = []
+        }
         menu.value = false
         if (!isPristine.value && search.value) {
           _searchLock.value = search.value

packages/vuetify/src/components/VCombobox/VCombobox.tsx

@@ -125,6 +125,9 @@ export const VCombobox = genericComponent<new <
     'update:modelValue': (value: any) => true,
     'update:search': (value: string) => true,
     'update:menu': (value: boolean) => true,
+    'item:added': (item: ListItem) => true,
+    'item:removed': (item: ListItem) => true,
+    'item:created': (item: ListItem) => true,
   },
 
   setup (props, { emit, slots }) {
@@ -166,6 +169,9 @@ export const VCombobox = genericComponent<new <
       set: async (val: string | null) => {
         _search.value = val ?? ''
         if (val === null || (val === '' && !props.multiple && !hasSelectionSlot.value)) {
+          for (const item of model.value) {
+            emit('item:removed', item)
+          }
           model.value = []
         } else if (!props.multiple && !hasSelectionSlot.value) {
           model.value = [transformItem(props, val)]
@@ -413,19 +419,30 @@ export const VCombobox = genericComponent<new <
       isPristine.value = true
       _searchLock.value = null
     }
+
+    function isExistingItem (item: ListItem) {
+      const comparator = props.valueComparator || deepEqual
+      return items.value.some(i => comparator(i.value, item.value))
+    }
+
     /** @param set - null means toggle */
     function select (item: ListItem | undefined, set: boolean | null = true, keepMenu = false) {
       if (!item || item.props.disabled) return
 
+      const comparator = props.valueComparator || deepEqual
+
       if (props.multiple) {
-        const index = model.value.findIndex(selection => (props.valueComparator || deepEqual)(selection.value, item.value))
+        const index = model.value.findIndex(selection => comparator(selection.value, item.value))
         const add = set == null ? !~index : set
 
         if (~index) {
           const value = add ? [...model.value, item] : [...model.value]
-          value.splice(index, 1)
+          const [removed] = value.splice(index, 1)
+          if (!add) emit('item:removed', removed) // skip if only reordered
           model.value = value
         } else if (add) {
+          emit('item:added', item)
+          if (!isExistingItem(item)) emit('item:created', item)
           model.value = [...model.value, item]
         }
 
@@ -434,7 +451,23 @@ export const VCombobox = genericComponent<new <
         }
       } else {
         const add = set !== false
-        model.value = add ? [item] : []
+        const old = model.value[0]
+
+        if (add) {
+          if (old && !comparator(old.value, item.value)) {
+            emit('item:removed', old)
+            emit('item:added', item)
+            if (!isExistingItem(item)) emit('item:created', item)
+          } else if (!old) {
+            emit('item:added', item)
+            if (!isExistingItem(item)) emit('item:created', item)
+          }
+          model.value = [item]
+        } else {
+          if (old) emit('item:removed', old)
+          model.value = []
+        }
+
         if ((!isPristine.value || props.alwaysFilter) && _search.value) {
           _searchLock.value = _search.value
         }

packages/vuetify/src/components/VCombobox/__tests__/VCombobox.spec.browser.tsx

@@ -921,5 +921,75 @@ describe('VCombobox', () => {
     expect(screen.getByRole('listbox').contains(document.activeElement)).toBe(true)
   })
 
+  describe('selection events for multiple', () => {
+    it('should emit item:created for free-text values', async () => {
+      const added = vi.fn()
+      const created = vi.fn()
+      const model = ref<string[]>([])
+
+      const { element } = render(() => (
+        <VCombobox
+          items={['Item 1', 'Item 2']}
+          multiple
+          modelValue={ model.value }
+          onUpdate:modelValue={ val => model.value = val as string[] }
+          onItem:added={ added }
+          onItem:created={ created }
+        />
+      ))
+
+      await userEvent.click(element)
+      await userEvent.keyboard('Brand new{Enter}')
+
+      expect(added).toHaveBeenCalledTimes(1)
+      expect(created).toHaveBeenCalledTimes(1)
+      expect(created.mock.calls[0][0]).toMatchObject({ title: 'Brand new', value: 'Brand new', raw: 'Brand new' })
+      expect(model.value).toEqual(['Brand new'])
+    })
+
+    it('should not emit item:created when selecting an existing item', async () => {
+      const added = vi.fn()
+      const created = vi.fn()
+      const model = ref<string[]>([])
+
+      const { element } = render(() => (
+        <VCombobox
+          items={['Item 1', 'Item 2']}
+          multiple
+          modelValue={ model.value }
+          onUpdate:modelValue={ val => model.value = val as string[] }
+          onItem:added={ added }
+          onItem:created={ created }
+        />
+      ))
+
+      await userEvent.click(element)
+      await commands.waitStable('.v-list')
+      await userEvent.click(screen.getAllByRole('option')[0])
+
+      expect(added).toHaveBeenCalledTimes(1)
+      expect(created).not.toHaveBeenCalled()
+    })
+
+    it('should emit item:removed when closing a chip', async () => {
+      const removed = vi.fn()
+
+      render(() => (
+        <VCombobox
+          items={['Item 1', 'Item 2']}
+          modelValue={['Item 1', 'Item 2']}
+          multiple
+          chips
+          closableChips
+          onItem:removed={ removed }
+        />
+      ))
+
+      await userEvent.click(screen.getAllByTestId('close-chip')[0])
+      expect(removed).toHaveBeenCalledTimes(1)
+      expect(removed.mock.calls[0][0]).toMatchObject({ title: 'Item 1', value: 'Item 1' })
+    })
+  })
+
   showcase({ stories })
 })

packages/vuetify/src/components/VSelect/VSelect.tsx

@@ -148,9 +148,11 @@ export const VSelect = genericComponent<new <
     'update:modelValue': (value: any) => true,
     'update:menu': (ue: boolean) => true,
     'update:search': (value: string) => true,
+    'item:added': (item: ListItem) => true,
+    'item:removed': (item: ListItem) => true,
   },
 
-  setup (props, { slots }) {
+  setup (props, { emit, slots }) {
     const { t } = useLocale()
     const vTextFieldRef = ref<VTextField>()
     const vMenuRef = ref<VMenu>()
@@ -280,6 +282,7 @@ export const VSelect = genericComponent<new <
 
       if (props.clearable && e.key === 'Backspace') {
         e.preventDefault()
+        for (const item of model.value) emit('item:removed', item)
         model.value = []
         onClear(e)
         return
@@ -343,28 +346,45 @@ export const VSelect = genericComponent<new <
       keyboardLookupIndex = index
       listRef.value?.focus(index)
       if (!props.multiple) {
-        model.value = [item]
+        select(item, true)
       }
     }
 
     /** @param set - null means toggle */
     function select (item: ListItem, set: boolean | null = true) {
       if (item.props.disabled) return
 
+      const comparator = props.valueComparator || deepEqual
+
       if (props.multiple) {
-        const index = model.value.findIndex(selection => (props.valueComparator || deepEqual)(selection.value, item.value))
+        const index = model.value.findIndex(selection => comparator(selection.value, item.value))
         const add = set == null ? !~index : set
 
         if (~index) {
           const value = add ? [...model.value, item] : [...model.value]
-          value.splice(index, 1)
+          const [removed] = value.splice(index, 1)
+          if (!add) emit('item:removed', removed) // skip if only reordered
           model.value = value
         } else if (add) {
+          emit('item:added', item)
           model.value = [...model.value, item]
         }
       } else {
         const add = set !== false
-        model.value = add ? [item] : []
+        const old = model.value[0]
+
+        if (add) {
+          if (old && !comparator(old.value, item.value)) {
+            emit('item:removed', old)
+            emit('item:added', item)
+          } else if (!old) {
+            emit('item:added', item)
+          }
+          model.value = [item]
+        } else {
+          if (old) emit('item:removed', old)
+          model.value = []
+        }
 
         nextTick(() => {
           menu.value = false
@@ -427,8 +447,10 @@ export const VSelect = genericComponent<new <
       }
     }
     function onModelUpdate (v: any) {
-      if (v == null) model.value = []
-      else if (matchesSelector(vTextFieldRef.value, ':autofill') || matchesSelector(vTextFieldRef.value, ':-webkit-autofill')) {
+      if (v == null) {
+        for (const item of model.value) emit('item:removed', item)
+        model.value = []
+      } else if (matchesSelector(vTextFieldRef.value, ':autofill') || matchesSelector(vTextFieldRef.value, ':-webkit-autofill')) {
         const item = items.value.find(item => item.title === v)
         if (item) {
           select(item)