Merge branch 'master' into generate-api-docs

.npmignore

@@ -0,0 +1,4 @@
+*
+!src/**/*
+!dist/**/*
+.DS_Store

docs/guide/accessibility.md

@@ -2,7 +2,7 @@ Vue Select aims to follow the WAI-ARIA best practices for the
 [combobox](https://www.w3.org/TR/wai-aria-practices-1.1/#combobox) and 
 [listbox](https://www.w3.org/TR/wai-aria-practices-1.1/#Listbox) widgets. 
 
-The UX of the component isdesigned around the HTML `<select>` element, while following the WAI-ARIA 
+The UX of the component is designed around the HTML `<select>` element, while following the WAI-ARIA 
 specifications and best practices for creating accessible components. 
 
 ## Combobox

docs/guide/values.md

@@ -127,7 +127,7 @@ To allow input that's not present within the options, set the `taggable` prop to
 If you want added tags to be pushed to the options array, set `push-tags` to true.
 
 ```html
-<v-select taggable multiple />
+<v-select taggable multiple push-tags />
 ```
 
 <v-select taggable multiple push-tags />

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-select",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Everything you wish the HTML <select> element could do, wrapped up into a lightweight, extensible Vue component.",
   "author": "Jeff Sagal <sagalbot@gmail.com>",
   "homepage": "https://vue-select.org",
@@ -35,7 +35,7 @@
     "@babel/plugin-transform-runtime": "^7.4.0",
     "@babel/preset-env": "^7.4.2",
     "@babel/runtime": "^7.4.2",
-    "@vue/test-utils": "^1.0.0-beta.29",
+    "@vue/test-utils": "^1.0.0-beta.31",
     "autoprefixer": "^9.4.7",
     "babel-core": "^7.0.0-bridge.0",
     "babel-loader": "^8.0.5",

src/components/Select.vue

@@ -414,11 +414,31 @@
       },
 
       /**
-       * When false, updating the options will not reset the select value
+       * When false, updating the options will not reset the selected value. Accepts
+       * a `boolean` or `function` that returns a `boolean`. If defined as a function,
+       * it will receive the params listed below.
+       *
+       * @since 3.4 - Type changed to {Boolean|Function}
+       *
+       * @type {Boolean|Function}
+       * @param {Array} newOptions
+       * @param {Array} oldOptions
+       * @param {Array} selectedValue
        */
       resetOnOptionsChange: {
-        type: Boolean,
+        default: false,
-        default: false
+        validator: (value) => ['function', 'boolean'].includes(typeof value)
+      },
+
+      /**
+       * If search text should clear on blur
+       * @return {Boolean} True when single and clearSearchOnSelect
+       */
+      clearSearchOnBlur: {
+        type: Function,
+        default: function ({ clearSearchOnSelect, multiple }) {
+          return clearSearchOnSelect && !multiple
+        }
       },
 
       /**
@@ -513,13 +533,17 @@
        * is correct.
        * @return {[type]} [description]
        */
-      options(val) {
+      options (newOptions, oldOptions) {
-        if (!this.taggable && this.resetOnOptionsChange) {
+        let shouldReset = () => typeof this.resetOnOptionsChange === 'function'
-          this.clearSelection()
+          ? this.resetOnOptionsChange(newOptions, oldOptions, this.selectedValue)
+          : this.resetOnOptionsChange;
+
+        if (!this.taggable && shouldReset()) {
+          this.clearSelection();
         }
 
         if (this.value && this.isTrackingValues) {
-          this.setInternalValueFromOptions(this.value)
+          this.setInternalValueFromOptions(this.value);
         }
       },
 
@@ -833,7 +857,8 @@
         if (this.mousedown && !this.searching) {
           this.mousedown = false
         } else {
-          if (this.clearSearchOnBlur) {
+          const { clearSearchOnSelect, multiple } = this;
+          if (this.clearSearchOnBlur({ clearSearchOnSelect, multiple })) {
             this.search = ''
           }
           this.closeSearchOptions()
@@ -990,7 +1015,7 @@
               'ref': 'search',
               'role': 'combobox',
               'type': 'search',
-              'autocomplete': 'off',
+              'autocomplete': this.autocomplete,
               'value': this.search,
             },
             events: {
@@ -1045,14 +1070,6 @@
         }
       },
 
-      /**
-       * If search text should clear on blur
-       * @return {Boolean} True when single and clearSearchOnSelect
-       */
-      clearSearchOnBlur() {
-        return this.clearSearchOnSelect && !this.multiple
-      },
-
       /**
        * Return the current state of the
        * search input

tests/unit/Ajax.spec.js

@@ -13,10 +13,11 @@ describe("Asynchronous Loading", () => {
     expect(Select.vm.mutableLoading).toEqual(true);
   });
 
-  it("should trigger the search event when the search text changes", () => {
+  it("should trigger the search event when the search text changes", async () => {
     const Select = selectWithProps();
 
     Select.vm.search = "foo";
+    await Select.vm.$nextTick();
 
     const events = Select.emitted("search");
 
@@ -24,11 +25,13 @@ describe("Asynchronous Loading", () => {
     expect(events.length).toEqual(1);
   });
 
-  it("should trigger the search event if the search text is empty", () => {
+  it("should trigger the search event if the search text is empty", async () => {
     const Select = selectWithProps();
 
     Select.vm.search = "foo";
+    await Select.vm.$nextTick();
     Select.vm.search = "";
+    await Select.vm.$nextTick();
 
     const events = Select.emitted("search");
 
@@ -36,7 +39,7 @@ describe("Asynchronous Loading", () => {
     expect(events.length).toEqual(2);
   });
 
-  it("can set loading to false from the @search event callback", () => {
+  it("can set loading to false from the @search event callback", async () => {
     const Select = shallowMount(vSelect, {
       listeners: {
         search: (search, loading) => {
@@ -47,13 +50,16 @@ describe("Asynchronous Loading", () => {
 
     Select.vm.mutableLoading = true;
     Select.vm.search = 'foo';
+    await Select.vm.$nextTick();
 
     expect(Select.vm.mutableLoading).toEqual(false);
   });
 
-  it("will sync mutable loading with the loading prop", () => {
+  it('will sync mutable loading with the loading prop', async () => {
     const Select = selectWithProps({ loading: false });
     Select.setProps({ loading: true });
+    await Select.vm.$nextTick();
+
     expect(Select.vm.mutableLoading).toEqual(true);
   });
 });

tests/unit/Deselecting.spec.js

@@ -1,9 +1,10 @@
 import { selectWithProps } from "../helpers";
 
 describe("Removing values", () => {
-  it("can remove the given tag when its close icon is clicked", () => {
+  it("can remove the given tag when its close icon is clicked", async () => {
     const Select = selectWithProps({ multiple: true });
     Select.vm.$data._value = 'one';
+    await Select.vm.$nextTick();
 
     Select.find(".vs__deselect").trigger("click");
     expect(Select.emitted().input).toEqual([[[]]]);

tests/unit/Labels.spec.js

@@ -12,13 +12,15 @@ describe("Labels", () => {
     expect(Select.find(".vs__selected").text()).toBe("Foo");
   });
 
-  it("will console.warn when options contain objects without a valid label key", () => {
+  it("will console.warn when options contain objects without a valid label key", async () => {
     const spy = jest.spyOn(console, "warn").mockImplementation(() => {});
     const Select = selectWithProps({
       options: [{}]
     });
 
     Select.vm.open = true;
+    await Select.vm.$nextTick();
+
     expect(spy).toHaveBeenCalledWith(
       '[vue-select warn]: Label key "option.label" does not exist in options object {}.' +
         "\nhttps://vue-select.org/api/props.html#getoptionlabel"

tests/unit/ReactiveOptions.spec.js

@@ -1,5 +1,6 @@
-import { shallowMount } from "@vue/test-utils";
+import { mount, shallowMount } from '@vue/test-utils';
 import VueSelect from "../../src/components/Select";
+import { mountDefault } from '../helpers';
 
 describe("Reset on options change", () => {
   it("should not reset the selected value by default when the options property changes", () => {
@@ -13,7 +14,81 @@ describe("Reset on options change", () => {
     expect(Select.vm.selectedValue).toEqual(["one"]);
   });
 
-  it("should reset the selected value when the options property changes", () => {
+  describe('resetOnOptionsChange as a function', () => {
+    it('will yell at you if resetOnOptionsChange is not a function or boolean', () => {
+      const spy = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+      mountDefault({resetOnOptionsChange: 1});
+      expect(spy.mock.calls[0][0]).toContain('Invalid prop: custom validator check failed for prop "resetOnOptionsChange"')
+
+      mountDefault({resetOnOptionsChange: 'one'});
+      expect(spy.mock.calls[1][0]).toContain('Invalid prop: custom validator check failed for prop "resetOnOptionsChange"')
+
+      mountDefault({resetOnOptionsChange: []});
+      expect(spy.mock.calls[2][0]).toContain('Invalid prop: custom validator check failed for prop "resetOnOptionsChange"')
+
+      mountDefault({resetOnOptionsChange: {}});
+      expect(spy.mock.calls[3][0]).toContain('Invalid prop: custom validator check failed for prop "resetOnOptionsChange"')
+    });
+
+    it('should receive the new options, old options, and current value', async () => {
+      let resetOnOptionsChange = jest.fn(option => option);
+      const Select = mountDefault(
+        {resetOnOptionsChange, options: ['bear'], value: 'selected'},
+      );
+
+      Select.setProps({options: ['lake', 'kite']});
+      await Select.vm.$nextTick();
+
+      expect(resetOnOptionsChange).toHaveBeenCalledTimes(1);
+      expect(resetOnOptionsChange)
+        .toHaveBeenCalledWith(['lake', 'kite'], ['bear'], ['selected']);
+    });
+
+    it('should allow resetOnOptionsChange to be a function that returns true', async () => {
+      let resetOnOptionsChange = () => true;
+      const Select = shallowMount(VueSelect, {
+        propsData: {resetOnOptionsChange, options: ['one'], value: 'one'},
+      });
+      const spy = jest.spyOn(Select.vm, 'clearSelection');
+
+      Select.setProps({options: ['one', 'two']});
+      await Select.vm.$nextTick();
+
+      expect(spy).toHaveBeenCalledTimes(1);
+    });
+
+    it('should allow resetOnOptionsChange to be a function that returns false', () => {
+      let resetOnOptionsChange = () => false;
+      const Select = shallowMount(VueSelect, {
+        propsData: {resetOnOptionsChange, options: ['one'], value: 'one'},
+      });
+      const spy = jest.spyOn(Select.vm, 'clearSelection');
+
+      Select.setProps({options: ['one', 'two']});
+      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it('should reset the options if the selectedValue does not exist in the new options', async () => {
+      let resetOnOptionsChange = (options, old, val) => val.some(val => options.includes(val));
+      const Select = shallowMount(VueSelect, {
+        propsData: {resetOnOptionsChange, options: ['one'], value: 'one'},
+      });
+      const spy = jest.spyOn(Select.vm, 'clearSelection');
+
+      Select.setProps({options: ['one', 'two']});
+      await Select.vm.$nextTick();
+
+      expect(Select.vm.selectedValue).toEqual(['one']);
+
+      Select.setProps({options: ['two']});
+      await Select.vm.$nextTick();
+
+      expect(spy).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("should reset the selected value when the options property changes", async () => {
     const Select = shallowMount(VueSelect, {
       propsData: { resetOnOptionsChange: true, options: ["one"] }
     });
@@ -21,15 +96,46 @@ describe("Reset on options change", () => {
     Select.vm.$data._value = 'one';
 
     Select.setProps({options: ["four", "five", "six"]});
+    await Select.vm.$nextTick();
+
     expect(Select.vm.selectedValue).toEqual([]);
   });
 
-  it("should return correct selected value when the options property changes and a new option matches", () => {
+  it("should return correct selected value when the options property changes and a new option matches", async () => {
     const Select = shallowMount(VueSelect, {
       propsData: { value: "one", options: [], reduce(option) { return option.value } }
     });
 
     Select.setProps({options: [{ label: "oneLabel", value: "one" }]});
+    await Select.vm.$nextTick();
+
     expect(Select.vm.selectedValue).toEqual([{ label: "oneLabel", value: "one" }]);
   });
+
+  it('default behavior when blur search field is to clean it.', () => {
+    const Select = mountDefault({});
+    let clearSearchOnBlur = jest.spyOn(Select.vm, 'clearSearchOnBlur');
+    Select.find({ ref: "search" }).trigger("click");
+    Select.setData({ search: "one" });
+    Select.find({ ref: "search" }).trigger("blur");
+
+    expect(clearSearchOnBlur).toHaveBeenCalledTimes(1);
+    expect(clearSearchOnBlur).toHaveBeenCalledWith({
+      clearSearchOnSelect: true,
+      multiple: false
+    });
+    expect(Select.vm.search).toBe('');
+  });
+
+  it('control behavior when blur search field.', () => {
+    let clearSearchOnBlur = jest.fn(() => false);
+    const Select = mountDefault({clearSearchOnBlur});
+
+    Select.find({ ref: "search" }).trigger("click");
+    Select.setData({ search: "one" });
+    Select.find({ ref: "search" }).trigger("blur");
+
+    expect(clearSearchOnBlur).toHaveBeenCalledTimes(1);
+    expect(Select.vm.search).toBe('one');
+  });
 });

tests/unit/Reduce.spec.js

@@ -211,7 +211,7 @@ describe("When reduce prop is defined", () => {
 
   });
 
-  it("reacts correctly when value property changes", () => {
+  it("reacts correctly when value property changes", async () => {
     const optionToChangeTo = { id: 1, label: "Foo" };
     const Select = shallowMount(VueSelect, {
       propsData: {
@@ -222,6 +222,7 @@ describe("When reduce prop is defined", () => {
     });
 
     Select.setProps({ value: optionToChangeTo.id });
+    await Select.vm.$nextTick();
 
     expect(Select.vm.selectedValue).toEqual([optionToChangeTo]);
   });

tests/unit/Selectable.spec.js

@@ -1,27 +1,33 @@
 import { selectWithProps } from "../helpers";
 
 describe("Selectable prop", () => {
-  it("should select selectable option if clicked", () => {
+  it("should select selectable option if clicked", async () => {
     const Select = selectWithProps({
       options: ["one", "two", "three"],
       selectable: (option) => option === "one"
     });
 
     Select.vm.$data.open = true;
+    await Select.vm.$nextTick();
 
     Select.find(".vs__dropdown-menu li:first-child").trigger("mousedown");
+
+    await Select.vm.$nextTick();
     expect(Select.vm.selectedValue).toEqual(["one"]);
   })
 
-  it("should not select not selectable option if clicked", () => {
+  it("should not select not selectable option if clicked", async () => {
     const Select = selectWithProps({
       options: ["one", "two", "three"],
       selectable: (option) => option === "one"
     });
 
     Select.vm.$data.open = true;
+    await Select.vm.$nextTick();
 
     Select.find(".vs__dropdown-menu li:last-child").trigger("mousedown");
+    await Select.vm.$nextTick();
+
     expect(Select.vm.selectedValue).toEqual([]);
   });
 

tests/unit/Slots.spec.js

@@ -42,7 +42,7 @@ describe('Scoped Slots', () => {
   });
 
   it('receives an option object to the option slot in the dropdown menu',
-    () => {
+    async () => {
       const Select = mountDefault(
         {value: 'one'},
         {
@@ -52,6 +52,7 @@ describe('Scoped Slots', () => {
         });
 
       Select.vm.open = true;
+      await Select.vm.$nextTick();
 
       expect(Select.find({ref: 'dropdownMenu'}).text()).toEqual('onetwothree');
     });

tests/unit/Tagging.spec.js

@@ -153,7 +153,7 @@ describe("When Tagging Is Enabled", () => {
     expect(Select.vm.selectedValue).toEqual([two]);
   });
 
-  it("should select an existing option if the search string matches an objects label from options", () => {
+  it("should select an existing option if the search string matches an objects label from options", async () => {
     let two = { label: "two" };
     const Select = selectWithProps({
       taggable: true,
@@ -161,12 +161,13 @@ describe("When Tagging Is Enabled", () => {
     });
 
     Select.vm.search = "two";
+    await Select.vm.$nextTick();
 
     searchSubmit(Select);
     expect(Select.vm.selectedValue).toEqual([two]);
   });
 
-  it("should select an existing option if the search string matches an objects label from options when filter-options is false", () => {
+  it("should select an existing option if the search string matches an objects label from options when filter-options is false", async () => {
     let two = { label: "two" };
     const Select = selectWithProps({
       taggable: true,
@@ -175,6 +176,7 @@ describe("When Tagging Is Enabled", () => {
     });
 
     Select.vm.search = "two";
+    await Select.vm.$nextTick();
 
     searchSubmit(Select);
     expect(Select.vm.selectedValue).toEqual([two]);

tests/unit/TypeAhead.spec.js

@@ -120,11 +120,12 @@ describe("Moving the Typeahead Pointer", () => {
   });
 
   describe("Measuring pixel distances", () => {
-    it("should calculate pointerHeight as the offsetHeight of the pointer element if it exists", () => {
+    it("should calculate pointerHeight as the offsetHeight of the pointer element if it exists", async () => {
       const Select = mountDefault();
 
       // Drop down must be open for $refs to exist
       Select.vm.open = true;
+      await Select.vm.$nextTick();
 
       /**
        * Since JSDom doesn't render layouts, set the offsetHeight explicitly