feat(select): add optionSelected and optionDeselected events

Author: TotomInc

docs/events.md

@@ -4,6 +4,46 @@ title: 'Events'
 
 # Events
 
-Currently, Vue 3 Select Component doesn't emit any custom events, except for the native `v-model` one.
-
 If you have the need for custom events, please open an issue on the [GitHub repository](https://github.com/TotomInc/vue3-select-component) with your use case and we will be happy to investigate it.
+
+## `@option-selected`
+
+Emitted when an option is selected, in the same tick where the `v-model` is updated.
+
+```vue
+<template>
+  <VueSelect
+    v-model="selectedValue"
+    :options="options"
+    @option-selected="(option) => console.log(option.label, option.value)"
+  />
+</template>
+```
+
+**Note**: this is emitted on the same tick as the v-model is updated, before a DOM re-render.
+
+::: info
+If you want to keep track of the selected option, it is recommended to use a `computed` combined with the `v-model`, instead of this event ([see this issue comment](https://github.com/TotomInc/vue3-select-component/issues/7#issuecomment-2083422621)).
+
+```ts
+const options = [{ label: "France", value: "FR" }, { label: "Spain", value: "ES" }];
+const activeValue = ref<string>();
+const selectedOption = computed(() => options.find((option) => option.value === activeValue.value));
+```
+:::
+
+## `@option-deselected`
+
+Emitted when an option is deselected, in the same tick where the `v-model` is updated.
+
+```vue
+<template>
+  <VueSelect
+    v-model="selectedValue"
+    :options="options"
+    @option-deselected="(option) => console.log(option.label, option.value)"
+  />
+</template>
+```
+
+**Note**: this is emitted on the same tick as the v-model is updated, before a DOM re-render.

src/Select.vue

@@ -101,6 +101,11 @@ const props = withDefaults(
   },
 );
 
+const emit = defineEmits<{
+  (e: "optionSelected", option: GenericOption): void;
+  (e: "optionDeselected", option: GenericOption | null): void;
+}>();
+
 /**
  * The value of the selected option. When `isMulti` prop is set to `true`, this
  * should be an array of `OptionValue`.
@@ -164,14 +169,16 @@ const closeMenu = () => {
   search.value = "";
 };
 
-const setOption = (value: OptionValue) => {
+const setOption = (option: GenericOption) => {
   if (props.isMulti) {
-    (selected.value as OptionValue[]).push(value);
+    (selected.value as OptionValue[]).push(option.value);
   }
   else {
-    selected.value = value;
+    selected.value = option.value;
   }
 
+  emit("optionSelected", option);
+
   search.value = "";
 
   if (props.closeOnSelect) {
@@ -183,18 +190,21 @@ const setOption = (value: OptionValue) => {
   }
 };
 
-const removeOption = (value: OptionValue) => {
+const removeOption = (option: GenericOption) => {
   if (props.isMulti) {
-    selected.value = (selected.value as OptionValue[]).filter((v) => v !== value);
+    selected.value = (selected.value as OptionValue[]).filter((value) => value !== option.value);
+    emit("optionDeselected", option);
   }
 };
 
 const clear = () => {
   if (props.isMulti) {
     selected.value = [];
+    emit("optionDeselected", null);
   }
   else {
     selected.value = undefined as OptionValue;
+    emit("optionDeselected", selectedOptions.value[0]);
   }
 
   menuOpen.value = false;
@@ -219,13 +229,13 @@ const handleNavigation = (e: KeyboardEvent) => {
 
     if (e.key === "Enter") {
       e.preventDefault();
-      setOption(filteredOptions.value[focusedOption.value].value);
+      setOption(filteredOptions.value[focusedOption.value]);
     }
 
     // When pressing space with menu open but no search, select the focused option.
     if (e.code === "Space" && search.value.length === 0) {
       e.preventDefault();
-      setOption(filteredOptions.value[focusedOption.value].value);
+      setOption(filteredOptions.value[focusedOption.value]);
     }
 
     if (e.key === "Escape") {
@@ -342,7 +352,7 @@ onBeforeUnmount(() => {
             :key="i"
             type="button"
             class="multi-value"
-            @click="removeOption(option.value)"
+            @click="removeOption(option)"
           >
             {{ getMultiValueLabel(option) }}
             <XMarkIcon />
@@ -421,7 +431,7 @@ onBeforeUnmount(() => {
           :index="i"
           :is-focused="focusedOption === i"
           :is-selected="option.value === selected"
-          @select="setOption(option.value)"
+          @select="setOption(option)"
         >
           <slot name="option" :option="option">
             {{ getOptionLabel(option) }}