add docs, update API

docs/.vuepress/components/CountrySelect.vue

@@ -12,5 +12,3 @@ export default {
   }),
 }
 </script>
-
-<style scoped></style>

docs/.vuepress/components/TranslationFrench.vue

@@ -0,0 +1,18 @@
+<template>
+  <v-select
+    :locale="locale"
+    :options="['un', 'deux', 'trois', 'quatre']"
+  ></v-select>
+</template>
+
+<script>
+import { locale as french } from 'vue-select/locales/fr.js'
+
+export default {
+  computed: {
+    locale() {
+      return () => french
+    },
+  },
+}
+</script>

docs/.vuepress/components/TranslationSingleKey.vue

@@ -0,0 +1,16 @@
+<template>
+  <v-select :locale="locale" :option="['one', 'two', 'three']" />
+</template>
+
+<script>
+export default {
+  computed: {
+    locale() {
+      return (text) => ({
+        ...text,
+        noOptions: { text: 'No Options found!!' },
+      })
+    },
+  },
+}
+</script>

docs/.vuepress/components/TranslationSpanish.vue

@@ -0,0 +1,17 @@
+<template>
+  <SpanishSelect :options="['uno', 'dos', 'tres', 'cuatro']" />
+</template>
+
+<script>
+import SpanishSelect from 'vue-select'
+import { locale as spanish } from 'vue-select/locales/es.js'
+
+SpanishSelect.props.locale = {
+  type: Function,
+  default: () => spanish,
+}
+
+export default {
+  components: { SpanishSelect },
+}
+</script>

docs/.vuepress/config.js

@@ -2,6 +2,7 @@ const { description } = require('./config/meta')
 const head = require('./config/head')
 const plugins = require('./config/plugins')
 const themeConfig = require('./config/themeConfig')
+const { resolve } = require('path')
 
 module.exports = {
   title: 'Vue Select',
@@ -9,4 +10,7 @@ module.exports = {
   head,
   plugins,
   themeConfig,
+  alias: {
+    'vue-select': resolve(__dirname, '../../src'),
+  },
 }

docs/.vuepress/config/themeConfig.js

@@ -37,7 +37,7 @@ module.exports = {
         collapsable: false,
         children: [
           ['guide/accessibility', 'WAI-ARIA Spec'],
-          ['guide/localization', 'Localization'],
+          ['guide/localization', 'Localization / i18n'],
         ],
       },
       {

docs/.vuepress/enhanceApp.js

@@ -1,4 +1,4 @@
-import vSelect from '../../src/components/Select'
+import vSelect from 'vue-select/components/Select'
 
 export default ({ Vue, options, router, siteData }) => {
   Vue.component('v-select', vSelect)

docs/guide/localization.md

@@ -1,45 +1,78 @@
+# Translations <Badge text="v3.13.0+" />
+
+There are a number of strings used within the component that can all be translated. Out of the box,
+Vue Select has translations for the following languages/locales that can be found
+in [`src/locales`](https://github.com/sagalbot/vue-select/tree/master/src/locales):
+
+- [English (default)](https://github.com/sagalbot/vue-select/tree/master/src/locales/en.js)
+- [French](https://github.com/sagalbot/vue-select/tree/master/src/locales/fr.js)
+- [Spanish](https://github.com/sagalbot/vue-select/tree/master/src/locales/es.js)
+
+Translations can be set on for each component instance, or globally for all instances in your app.
+Both methods will use the `locale` prop to determine the text to be used throughout the component.
+
+**Locale Prop**
+
+The `locale` prop accepts a function and should return an object of translated strings. The function
+receives the default english translations for the component. This allows you to override the whole
+object, or change just the values you need. The structure of the returned `locale` object is
+described below.
+
+**Locale Object**
+
+The object returned from the locale prop requires specific keys to be set. Below is an example from
+the english locale that ships with Vue Select:
+
+<<< @/../src/locales/en.js
+
+# Examples
+---
+
+## Translate a Single Instance
+
+Translating a single instance of Vue Select can be accomplished by setting the `locale` function to
+return an object with the translations you need. In the example below, we use the french `locale`
+object that ships with Vue Select.
+
+<TranslationFrench />
+<<< @/.vuepress/components/TranslationFrench.vue
+
+**Modifying Specific Text**
+
+You can also use the `locale` prop to override just the text that you'd like to change. In this
+example, the text in the `no-options` slot is updated to say 'No Options found!!'.
+
+<TranslationSingleKey />
+<<< @/.vuepress/components/TranslationSingleKey.vue
+
+## Translate all Instances
+
+If you'd like to translate the text for **all** Vue Select instances in your app, you can override
+the default prop when registering the component. In the example below, all instances of Vue Select
+will be translated to Spanish.
+
+<TranslationSpanish />
+<<< @/.vuepress/components/TranslationSpanish.vue
+
 ## Right to Left
 
 Vue Select supports RTL using the standard HTML API using the `dir` prop.
 
-```html
+```vue
+
 <v-select dir="rtl"></v-select>
 ```
 
-The `dir` prop accepts the same values as the [HTML spec](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir): 
+The `dir` prop accepts the same values as
+the [HTML spec](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir):
 
-  - `rtl`
+- `rtl`
-  - `ltr`
+- `ltr`
-  - `auto`
+- `auto`
 
-## Component Text
+## Contributing Languages
 
-All of the text within the component has been wrapped within [slots](https://vuejs.org/v2/guide/components.html#Content-Distribution-with-Slots) and can be replaced in your app.
+If you'd like to see Vue Select translated to a new language, submit a PR with a new
-
+`locale` file in the `src/locales` folder. The file name should match
-### Loading Spinner
+the [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for the language, and
-*Slot Definition:*
+export a `locale` object.
-```html
-<slot name="spinner">
-	<div class="spinner" v-show="mutableLoading">Loading...</div>
-</slot>
-```
-*Implementation:*
-```html
-<v-select>
-	<i slot="spinner" class="icon icon-spinner"></i>
-</v-select>
-```
-
-### No Options Text
-*Slot Definition:*
-```html
-<slot name="no-options">Sorry, no matching options.</slot>
-```
-*Implementation:*
-```html
-<v-select>
-	<div slot="no-options">No Options Here!</div>
-</v-select>
-```
-
-For a full list of component slots, view the [slots API docs](../api/slots.md).

src/components/Select.vue

@@ -64,8 +64,8 @@
           :disabled="disabled"
           type="button"
           class="vs__clear"
-          title="Clear Selected"
+          :title="i18n.clearButton.title"
-          aria-label="Clear Selected"
+          :aria-label="i18n.clearButton.ariaLabel"
           @click="clearSelection"
         >
           <component :is="childComponents.Deselect" />

src/locales/en.js

@@ -0,0 +1,19 @@
+export const locale = {
+  spinner: {
+    text: 'Loading...',
+  },
+  noOptions: {
+    text: 'Sorry, no matching options.',
+  },
+  search: {
+    ariaLabel: 'Search for options',
+  },
+  deselectButton: {
+    ariaLabel: (label) => `Deselect ${label}`,
+    title: (label) => `Deselect ${label}`,
+  },
+  clearButton: {
+    ariaLabel: 'Clear Selection',
+    title: 'Clear Selection',
+  },
+}

src/locales/es.js

@@ -0,0 +1,19 @@
+export const locale = {
+  spinner: {
+    text: 'Cargando...',
+  },
+  noOptions: {
+    text: 'Lo sentimos, no hay opciones que coincidan.',
+  },
+  search: {
+    ariaLabel: 'Buscar opciones',
+  },
+  deselectButton: {
+    ariaLabel: (label) => `Deseleccionar ${label}`,
+    title: (label) => `Deseleccionar ${label}`,
+  },
+  clearButton: {
+    ariaLabel: 'Eliminar selección',
+    title: 'Eliminar selección',
+  },
+}

src/locales/fr.js

@@ -0,0 +1,19 @@
+export const locale = {
+  spinner: {
+    text: 'Chargement...',
+  },
+  noOptions: {
+    text: 'Désolé, aucune option correspondante.',
+  },
+  search: {
+    ariaLabel: 'Rechercher des options',
+  },
+  deselectButton: {
+    ariaLabel: (label) => `Désélectionner ${label}`,
+    title: (label) => `Désélectionner ${label}`,
+  },
+  clearButton: {
+    ariaLabel: 'Effacer la sélection',
+    title: 'Effacer la sélection',
+  },
+}

src/mixins/i18n.js

@@ -1,25 +1,4 @@
-const deselectLabel = (label) => `Deselect ${label}`
+import { locale as english } from '../locales/en.js'
-
-export const text = {
-  spinner: {
-    text: 'Loading...',
-  },
-  noOptions: {
-    text: 'Sorry, no matching options.',
-  },
-  search: {
-    ariaLabel: 'Search for options',
-  },
-  selectedOption: {},
-  deselectButton: {
-    ariaLabel: deselectLabel,
-    title: deselectLabel,
-  },
-  clearButton: {
-    ariaLabel: 'Clear Selection',
-    title: 'Clear Selection',
-  },
-}
 
 /**
  * @this VueSelect
@@ -27,18 +6,18 @@ export const text = {
  */
 export default {
   props: {
-    text: {
+    locale: {
       type: Function,
       /**
        * @param text {Object}
-       * @return {*}
+       * @return {Object}
        */
       default: (text) => text,
     },
   },
   computed: {
     i18n() {
-      return this.text(text)
+      return this.locale(english)
     },
   },
 }