From 5492ee1126f7b8ec6c05b398cd0b0a3c867864d2 Mon Sep 17 00:00:00 2001
From: Jeff Sagal <sagalbot@gmail.com>
Date: Mon, 29 Apr 2019 22:08:56 -0700
Subject: [PATCH] add accessibility documentation (#867)

---
 .../components/ClearButtonOverride.vue        |  2 +
 .../components/OpenIndicatorOverride.vue      |  5 +-
 docs/.vuepress/config.js                      |  9 ++-
 docs/guide/accessibility.md                   | 64 +++++++++++++++++++
 docs/guide/components.md                      |  9 +--
 docs/guide/localization.md                    | 10 ++-
 6 files changed, 87 insertions(+), 12 deletions(-)
 create mode 100644 docs/guide/accessibility.md

diff --git a/docs/.vuepress/components/ClearButtonOverride.vue b/docs/.vuepress/components/ClearButtonOverride.vue
index 11b6c58..837ea68 100644
--- a/docs/.vuepress/components/ClearButtonOverride.vue
+++ b/docs/.vuepress/components/ClearButtonOverride.vue
@@ -1,6 +1,7 @@
 <template>
   <div>
     <v-select
+            v-model="selected"
             :options="['Canada', 'United States']"
             :components="{Deselect}"
     />
@@ -10,6 +11,7 @@
 <script>
 export default {
   data: () => ({
+    selected: 'Canada',
     Deselect: {
       render: createElement => createElement('span', '❌'),
     },
diff --git a/docs/.vuepress/components/OpenIndicatorOverride.vue b/docs/.vuepress/components/OpenIndicatorOverride.vue
index 8f5b76e..a44961c 100644
--- a/docs/.vuepress/components/OpenIndicatorOverride.vue
+++ b/docs/.vuepress/components/OpenIndicatorOverride.vue
@@ -1,8 +1,6 @@
 <template>
   <div>
     <v-select
-            multiple
-            v-model="selected"
             :options="['Canada', 'United States']"
             :components="{OpenIndicator}"
     />
@@ -12,9 +10,8 @@
 <script>
 export default {
   data: () => ({
-    selected: ['Canada'],
     OpenIndicator: {
-      render: createElement => createElement('span', {class: {'toggle': true}}),
+      render: createElement => createElement('span', '🔽'),
     },
   }),
 };
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 9f9163e..0ff773b 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -93,7 +93,6 @@ module.exports = {
             ['guide/install', 'Installation'],
             ['guide/options', 'Dropdown Options'],
             ['guide/values', 'Selecting Values'],
-            ['guide/localization', 'Localization'],
             ['guide/upgrading', 'Upgrading 2.x to 3.x'],
           ],
         },
@@ -106,6 +105,14 @@ module.exports = {
             ['guide/slots', 'Slots'],
           ],
         },
+        {
+          title: 'Accessibility',
+          collapsable: false,
+          children: [
+            ['guide/accessibility', 'WAI-ARIA Spec'],
+            ['guide/localization', 'Localization'],
+          ],
+        },
         {
           title: 'Digging Deeper',
           collapsable: false,
diff --git a/docs/guide/accessibility.md b/docs/guide/accessibility.md
new file mode 100644
index 0000000..1cc86f0
--- /dev/null
+++ b/docs/guide/accessibility.md
@@ -0,0 +1,64 @@
+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 
+specifications and best practices for creating accessible components. 
+
+## Combobox
+
+- [WAI-ARIA Combobox - Best Practices](https://www.w3.org/TR/wai-aria-practices-1.1/#combobox)
+- [WAI-ARIA Combobox - Specification](https://www.w3.org/TR/wai-aria-1.1/#combobox)
+
+## Listbox
+
+- [WAI-ARIA Listbox - Best Practices](https://www.w3.org/TR/wai-aria-practices-1.1/#Listbox)
+
+### Autocomplete
+
+WAI-ARIA suggests four forms of autocomplete for Comboboxes. Vue Select can be configured to provide
+these use cases.
+
+1. **No autocomplete** 
+
+    > When the popup is triggered, the suggested values it contains are the same regardless of the 
+    characters typed in the textbox. 
+  
+    ```html
+    <v-select :filterable="false" :options="['No Autocomplete', 'List Autocomplete']" />
+    ```
+    <v-select :filterable="false" :options="['No Autocomplete', 'List Autocomplete']" />
+
+2. **List autocomplete with manual selection**
+
+    > When the popup is triggered, it presents suggested values that complete or logically 
+    correspond to the characters typed in the textbox. The character string the user has 
+    typed will become the value of the textbox unless the user selects a value in the popup.
+
+    ```html
+    <v-select taggable :options="['No Autocomplete', 'List Autocomplete']" />
+    ```
+    <v-select taggable :options="['No Autocomplete', 'List Autocomplete']" />
+
+3. **List autocomplete with automatic selection**
+ 
+    > When the popup is triggered, it presents suggested values that complete or logically 
+    correspond to the characters typed in the textbox, and the first suggestion is automatically 
+    highlighted as selected. The automatically selected suggestion becomes the value of the textbox 
+    when the combobox loses focus unless the user chooses a different suggestion or changes the 
+    character string in the textbox.
+
+    ```html
+    <v-select :options="['No Autocomplete', 'List Autocomplete']" />
+    ```
+    <v-select :options="['No Autocomplete', 'List Autocomplete']" />
+
+4. **List with inline autocomplete** 
+    
+    > This is the same as list with automatic selection with one additional feature. The portion of 
+    the selected suggestion that has not been typed by the user, a completion string, appears inline
+     after the input cursor in the textbox. The inline completion string is visually highlighted and
+      has a selected state.
+      
+    🚧 Vue Select does not yet support this configuration, but it is on the roadmap 
+    [#865](https://github.com/sagalbot/vue-select/issues/865). 🚧
diff --git a/docs/guide/components.md b/docs/guide/components.md
index 7720404..7e91b7a 100644
--- a/docs/guide/components.md
+++ b/docs/guide/components.md
@@ -1,8 +1,9 @@
-Vue Select utilizes child components throughout, and exposes an API to overwrite these components 
-with your own, using the `components` `{Object}` prop. When implementing the `components` prop in 
-your code, Vue Select merge it's default components with any keys that you set in the object.
+### Prop: `components` `{Object}`
+---
 
-Your object will be merged with the object that is exported below:
+Vue Select utilizes child components throughout, and exposes an API to overwrite these components 
+with your own, using the `components` `{Object}` prop. The object provided to the `components` prop 
+will be merged with Vue Select's default components. 
                    
 <<< @/src/components/childComponents.js{4-7}
 
diff --git a/docs/guide/localization.md b/docs/guide/localization.md
index b35a91f..412edb5 100644
--- a/docs/guide/localization.md
+++ b/docs/guide/localization.md
@@ -1,12 +1,16 @@
-## RTL
+## Right to Left
 
-vue-select supports RTL using the standard HTML API using the `dir` attribute.
+Vue Select supports RTL using the standard HTML API using the `dir` prop.
 
 ```html
 <v-select dir="rtl"></v-select>
 ```
 
-The `dir` attribute accepts the same values as the [HTML spec](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir): `rtl`,`ltr`, and `auto`.
+The `dir` prop accepts the same values as the [HTML spec](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir): 
+
+  - `rtl`
+  - `ltr`
+  - `auto`
 
 ## Component Text