Merge branch 'master' into customizable-text

docs/.vuepress/components/Sponsors.vue

@@ -16,11 +16,11 @@ import { format } from "date-fns";
 
 export default {
   data: () => ({
-    sponsors: SPONSORS.map(({ createdAt, sponsor }) => ({
+    sponsors: SPONSORS.map(({ createdAt, sponsorEntity }) => ({
       createdAt: format(new Date(createdAt), "LLL yyyy"),
-      ...sponsor
+      ...sponsorEntity
     }))
-  })
+  }),
 };
 </script>
 

docs/.vuepress/github/clientDynamicModules.js

@@ -28,20 +28,28 @@ async function getContributors() {
  */
 async function getSponsors() {
   const query = `
-        {
+    {
-          user(login: "sagalbot") {
+      user(login: "sagalbot") {
-            sponsorshipsAsMaintainer(first: 100) {
+        sponsorshipsAsMaintainer(first: 100) {
-              nodes {
+          nodes {
-                createdAt
+            sponsorEntity {
-                sponsor {
+              ... on User {
-                  login
+                id
-                  avatarUrl
+                avatarUrl
-                }
+                login
+              }
+              ... on Organization {
+                id
+                avatarUrl
+                login
               }
             }
+            createdAt
           }
         }
-      `;
+      }
+    }
+  `;
 
   try {
     const { user } = await graphql(query, {

docs/.vuepress/theme/layouts/Layout.vue

@@ -1,17 +1,13 @@
 <template>
-  <ParentLayout>
+  <ParentLayout></ParentLayout>
-    <EthicalAds slot="sidebar-top" />
-  </ParentLayout>
 </template>
 
 <script>
 import ParentLayout from "@parent-theme/layouts/Layout.vue";
-import EthicalAds from "../components/EthicalAds.vue";
 
 export default {
   components: {
     ParentLayout,
-    EthicalAds
   }
 };
 </script>

docs/api/events.md

@@ -4,11 +4,27 @@ Triggered when the selected value changes. Used internally for `v-model`.
 
 ```js
 /**
- * @param val {Object|String}` - selected option.
+ * @param {Object|String} val - selected option.
  */
 this.$emit("input", val);
 ```
 
+## `open`
+
+Triggered when the dropdown is open.
+
+```js
+this.$emit("open");
+```
+
+## `close`
+
+Triggered when the dropdown is closed.
+
+```js
+this.$emit("close");
+```
+
 ## `option:selecting` <Badge text="v3.11.0+" />
 
 Triggered after an option has been selected, <strong>before</strong> updating internal state. 
@@ -47,11 +63,40 @@ Triggered when `taggable` is `true` and a new option has been created.
 
 ```js
 /**
- * @param newOption {Object} - created option
+ * @param {Object} newOption - created option
  */
 this.$emit("option:created", newOption);
 ```
 
+## `search`
+
+Anytime the search string changes, emit the
+'search' event. The event is passed with two 
+parameters: the search string, and a function 
+that accepts a boolean parameter to toggle the 
+loading state.
+
+See the [AJAX Guide](/guide/ajax.html#loading-options-with-ajax) 
+for a complete example.
+
+```js
+/**
+ * @param {String} searchString - the search string
+ * @param {Function} toggleLoading - function to toggle loading state, accepts true or false boolean
+ */
+this.$emit('search', this.search, this.toggleLoading);
+```
+
+```vue
+<!-- example usage -->
+<v-select
+    @search="(search, loading) => { 
+      loading(true)
+      fetchOptions(search).then(() => loading(false))
+    }"
+/>
+```
+
 ## `search:blur`
 
 Triggered when the text input loses focus. The dropdown will close immediately before this
@@ -69,3 +114,21 @@ event is triggered.
 ```js
 this.$emit("search:focus");
 ```
+
+## `search`
+
+Triggered when the search text changes.
+
+```js
+/**
+ * Anytime the search string changes, emit the
+ * 'search' event. The event is passed with two
+ * parameters: the search string, and a function
+ * that accepts a boolean parameter to toggle the
+ * loading state.
+ *
+ * @emits search
+ */
+this.$emit('search', newSearchString, toggleLoading);
+```
+

docs/api/props.md

@@ -187,6 +187,21 @@ disabled: {
 },
 ```
 
+## dropdownShouldOpen <Badge text="v3.12.0+" />
+
+Determines whether the dropdown should open. Used 
+for overriding the default dropdown behaviour. Receives
+the vue-select instance as the single argument to the function.
+
+```js
+dropdownShouldOpen: {
+    type: Function,
+    default({noDrop, open, mutableLoading}) {
+      return noDrop ? false : open && !mutableLoading;
+    }
+}
+```
+
 
 ## filter
 

docs/guide/components.md

@@ -58,7 +58,7 @@ export default {
 
 ## Setting Globally at Registration
 
-If you want to all instances of Vue Select to use your custom components throughout your app, while
+If you want all instances of Vue Select to use your custom components throughout your app, while
 only having to set the implementation once, you can do so when registering Vue Select as a component.
 
 ```js

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-select",
-  "version": "3.11.2",
+  "version": "3.12.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",

src/components/Select.vue

@@ -565,6 +565,20 @@
           dropdownList.style.left = left;
           dropdownList.style.width = width;
         }
+      },
+
+      /**
+       * Determines whether the dropdown should be open.
+       * Receives the component instance as the only argument.
+       *
+       * @since v3.12.0
+       * @return boolean
+       */
+      dropdownShouldOpen: {
+        type: Function,
+        default({noDrop, open, mutableLoading}) {
+          return noDrop ? false : open && !mutableLoading;
+        }
       }
     },
 
@@ -1132,7 +1146,7 @@
        * @return {Boolean} True if open
        */
       dropdownOpen() {
-        return this.noDrop ? false : this.open && !this.mutableLoading
+        return this.dropdownShouldOpen(this);
       },
 
       /**

tests/unit/Dropdown.spec.js

@@ -188,4 +188,14 @@ describe("Toggling Dropdown", () => {
     expect(Select.classes('vs--searching')).toBeFalsy();
   });
 
+  it("can be opened with dropdownShouldOpen", () => {
+    const Select = selectWithProps({
+      noDrop: true,
+      dropdownShouldOpen: () => true,
+      options: ['one']
+    });
+
+    expect(Select.classes('vs--open')).toBeTruthy();
+    expect(Select.find('.vs__dropdown-menu li')).toBeTruthy();
+  })
 });