overhaul selecting docs, updated navigation and URL structure

docs/.vuepress/components/CountrySelect.vue

@@ -0,0 +1,18 @@
+<template>
+  <v-select :options="options"></v-select>
+</template>
+
+<script>
+import countryCodes from '../data/countryCodes';
+
+export default {
+  name: 'CountrySelect',
+  data: () => ({
+    options: countryCodes,
+  }),
+};
+</script>
+
+<style scoped>
+
+</style>

docs/.vuepress/components/ReducerNestedValue.vue

@@ -0,0 +1,60 @@
+<template>
+  <div class="flex">
+    <div>
+      <v-select
+              label="country"
+              v-model="selected"
+              :reduce="opt => opt.meta.id"
+              :options="options"
+      />
+    </div>
+    <div>
+      <pre><code>v-model value: {{ selected || 'null' }}</code></pre>
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'ReducerNestedValue',
+  data: () => ({
+    selected: null,
+    options: [
+      {
+        country: 'canada',
+        meta: {
+          id: '1',
+          code: 'ca',
+        },
+      }],
+  }),
+};
+</script>
+
+<style scoped>
+  .flex {
+    margin-bottom: 2rem;
+    border: 1px solid #eaecef;
+    /*padding: 1rem;*/
+    display: flex;
+    justify-content: center;
+    align-items: center;
+  }
+
+  .flex > div {
+    flex-grow: 1;
+    width: 50%;
+    padding: 0 1rem;
+  }
+
+  pre {
+    margin: 0;
+    background: #fff;
+  }
+
+  code {
+    color: #635762 !important;
+    color: #5b2d2d !important;
+    /*color: #7ec699 !important;*/
+  }
+</style>

docs/.vuepress/config.js

@@ -74,19 +74,19 @@ module.exports = {
           title: 'Getting Started',
           collapsable: false,
           children: [
-            ['getting-started/install', 'Installation'],
+            ['guide/install', 'Installation'],
-            ['getting-started/options', 'Dropdown Options'],
+            ['guide/options', 'Dropdown Options'],
-            ['getting-started/values', 'Selecting Values'],
+            ['guide/values', 'Selecting Values'],
-            ['getting-started/localization', 'Localization'],
+            ['guide/localization', 'Localization'],
           ],
         },
         {
           title: 'Digging Deeper',
           collapsable: false,
           children: [
-            ['digging-deeper/templating', 'Templating & Slots'],
+            ['guide/templating', 'Templating & Slots'],
-            ['digging-deeper/vuex', 'Vuex'],
+            ['guide/vuex', 'Vuex'],
-            ['digging-deeper/ajax', 'AJAX'],
+            ['guide/ajax', 'AJAX'],
           ],
         },
         {

docs/getting-started/values.md

@@ -1,79 +0,0 @@
-## Getting / Setting
-
-### `v-model`
-
-The most common use case for `vue-select` is to have the chosen value synced with a parent component. `vue-select` 
-takes advantage of the `v-model` syntax to sync values with a parent.
-
-```html
-<v-select v-model="selected" />
-```
-
-### `value` prop & `input` event
-
-If you don't require the `value` to be synced, but you need to preselect a value, you can use the `value` prop. It will
-accept strings, numbers or objects. If you're using a `multiple` v-select, you'll want to pass an array. 
-
-```html
-<v-select :value="selected" />
-```
-
-The `value` prop is very useful when using a state management tool, like Vuex. `vue-select` will emit an `input` event 
-any time a value changes.
-
-```html
-<v-select :value="selected" @input="setSelected" />
-```
-
-```js
-methods: {
-  setSelected(value) {
-     //  do something with selected value  
-  }
-}
-```
-## Transforming Selections
-
-When the `options` array contains objects, `vue-select` returns the whole object as dropdown value upon selection.
-
-If you need to return a single key, or transform the data before it is synced, `vue-select` provides a `reduce` callback
- that allows you to transform a selected option before it is passed to the `@input` event. Consider this data structure:
- 
- ```js
- let options = [{code: 'CA', country: 'Canada'}, ...];
- ```
- 
- If we want to display the `country`, but return the `code` to `v-model`, we can use the `reduce` prop to receive
- only the data that's required.
- 
- ```html
- <v-select :options="options" :reduce="country => country.code" label="country" />
- ```
-  
-The `reduce` property also works well when you have a deeply nested value:
- 
- ```
- {
-   country: 'canada',
-   meta: {
-     id: '1',
-     code: 'ca'
-   }
- }
- ```
- 
- ```html
- <v-select :options="options" :reduce="country => country.value.id" label="country" />
- ```
-
-## Single/Multiple Selection
-
-By default, `vue-select` supports choosing a single value. If you need multiple values, use the `multiple` boolean prop,
-much the same way you would on a native `<select>` element. When `multiple` is true, `v-model` or `value` should be
-arrays.
- 
-
-```html
-<v-select multiple v-model="selected" :options="['foo','bar']" />
-```
-<v-select multiple :options="['foo','bar']" />

docs/guide/localization.md

@@ -39,5 +39,3 @@ All of the text within the component has been wrapped within [slots](https://vue
 ```
 
 For a full list of component slots, view the [slots API docs](../api/slots.md).
-
-<CodePen url="oZmLVN" height="450"/>

docs/guide/options.md

@@ -7,23 +7,29 @@
 ```html
 <!-- array of strings or numbers -->
 <v-select :options="['foo','bar']"></v-select>
+```
 
+<v-select :options="['foo','bar']"></v-select>
+
+```html
 <!-- or, an array of objects -->
 <v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
 ```
 
+<v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
+
 ## Option Labels
 
-#### Option Primitives (strings, numbers)
+#### Options as Primitives (strings, numbers, boolean)
 
 When `options` contains strings or numbers, they'll be used as the label for the option within the
 component. No further configuration is necessary. 
 
-#### Option Objects
+#### Options as Objects
 
-When `options` is an array of objects, the component must generate a label to be shown as the options text. By default, 
+When `options` is an array of objects, the component must generate a label to be shown as the 
-`vue-select` will attempt to render `option.label` as the option label. You can set your own label to match your 
+options text. By default, `vue-select` will attempt to render `option.label` as the option label. 
-source data using the `label` prop.
+You can set your own label to match your source data using the `label` prop.
 
 For example, consider an object with `countryCode` and `countryName` properties:
 
@@ -40,15 +46,17 @@ If you wanted to display `Canada` in the dropdown, you'd use the `countryName` k
 <v-select label="countryName" :options="countries"></v-select>
 ```
 
-<CodePen url="aEjLPB" height="450"/>
+<country-select />
 
 ## Null / Empty Options
 
-`vue-select` requires the `option` property to be an `array`. If you are using Vue in development mode, you will get warnings attempting to pass anything other than an `array` to the `options` prop. If you need a `null`/`empty` value, use an empty array `[]`.
+`vue-select` requires the `option` property to be an `array`. If you are using Vue in development 
+mode, you will get warnings attempting to pass anything other than an `array` to the `options` prop. 
+If you need a `null`/`empty` value, use an empty array `[]`.
 
 ## Tagging
 
 To allow input that's not present within the options, set the `taggable` prop to true.
 If you want new tags to be pushed to the options list, set `push-tags` to true.
 
-<CodePen url="XVoWxm" height="350"/>
+<v-select taggable />

docs/guide/values.md

@@ -0,0 +1,107 @@
+## Getting / Setting
+
+### `v-model`
+
+The most common use case for vue-select is to have the chosen value synced with a parent component. vue-select 
+takes advantage of the `v-model` syntax to sync values with a parent. The `v-model` syntax works with
+primitives and objects. 
+
+```html
+<v-select v-model="selected" />
+```
+
+Note that when using the `multiple` prop, the `v-model` value will always be an array.
+
+### Props and Events
+
+Sometimes `v-model` might not fit your use case. For example, when working with [Vuex](https://vuex.vuejs.org),
+you'll need to trigger a mutation rather than mutating a value directly. In that case, maybe you need
+to bind a pre-selected value, and trigger a mutation when it changes. 
+
+vue-select exposes the `value` prop and an `input` event to enable this. This combo of props and 
+events is also how Vue wires up the `v-model` syntax internally.
+
+#### Prop: `value`
+
+The `value` prop lets vue-select know what value is currently selected. It will accept strings, 
+numbers or objects. If you're using a `multiple` v-select, you'll want to pass an array. 
+
+```html
+<v-select :value="selected" />
+```
+
+::: tip 🤓
+Anytime you bind the `value` prop directly, you're responsible for updating the bound variable
+in your code using the `@input` event.
+:::
+
+#### Event: `input`
+
+The `input` event is triggered anytime the value state changes, and is emitted with the `value`
+state as it's only parameter.
+
+#### Vuex Support
+
+The `value` prop and `emit` event are very useful when using a state management tool, like Vuex. 
+You can bind the selected value with `:value="$store.myValue"`, and use the `input` event to
+trigger a mutation, or dispatch an action – or anything else you might need to do when the selection
+changes.
+
+```html
+<v-select :value="$store.myValue" @input="setSelected" />
+```
+
+```js
+methods: {
+  setSelected(value) {
+     //  trigger a mutation, or dispatch an action  
+  }
+}
+```
+## Transforming Selections
+
+When the `options` array contains objects, vue-select returns the whole object as dropdown value upon selection.
+
+If you need to return a single key, or transform the data before it is synced, vue-select provides a `reduce` callback
+ that allows you to transform a selected option before it is passed to the `@input` event. Consider this data structure:
+ 
+ ```js
+ let options = [{code: 'CA', country: 'Canada'}, ...];
+ ```
+ 
+ If we want to display the `country`, but return the `code` to `v-model`, we can use the `reduce` prop to receive
+ only the data that's required.
+ 
+ ```html
+ <v-select :options="options" :reduce="country => country.code" label="country" />
+ ```
+ 
+The `reduce` property also works well when you have a deeply nested value:
+ 
+ ```
+ {
+   country: 'canada',
+   meta: {
+     id: '1',
+     code: 'ca'
+   }
+ }
+ ```
+ 
+ ```html
+ <v-select :options="options" :reduce="country => country.value.id" label="country" />
+ ```
+ 
+ <reducer-nested-value />
+
+## Single/Multiple Selection
+
+By default, vue-select supports choosing a single value. If you need multiple values, use the `multiple` boolean prop,
+much the same way you would on a native `<select>` element. When `multiple` is true, `v-model` or `value` should be
+arrays.
+ 
+
+```html
+<v-select multiple v-model="selected" :options="['foo','bar']" />
+```
+<v-select multiple :options="['foo','bar']" />