From f007e842a498c3750428aac0ed65f54726478a28 Mon Sep 17 00:00:00 2001
From: Jeff <sagalbot@gmail.com>
Date: Wed, 4 Mar 2020 17:24:13 -0800
Subject: [PATCH] WIP slots documentation

---
 docs/api/slots.md   | 71 +++++++++++++++++++++++++++++++++++++++++++++
 docs/guide/slots.md | 38 ++++++++++++++++++------
 2 files changed, 100 insertions(+), 9 deletions(-)

diff --git a/docs/api/slots.md b/docs/api/slots.md
index e69de29..e4d15fc 100644
--- a/docs/api/slots.md
+++ b/docs/api/slots.md
@@ -0,0 +1,71 @@
+## selected-option
+
+```vue
+<slot name="selected-option" v-for="selected in scopedValues" v-bind="selected">
+  <span :class="selected.bindings.class">
+    {{ selected.label }}
+    <component
+    ref="deselectButtons"
+    :is="selected.deselect.component"
+    v-if="selected.deselect.bindings.multiple"
+    v-bind="selected.deselect.bindings"
+    v-on="selected.deselect.events"
+    />
+  </span>
+</slot>
+```
+
+## search
+
+```vue
+<slot name="search" v-bind="scope.search">
+  <input v-bind="scope.search.attributes" v-on="scope.search.events">
+</slot>
+```
+
+## clear
+
+```vue
+<slot name="clear">
+  <component
+    ref="clearButton"
+    :is="scope.clear.component"
+    v-bind="scope.clear.bindings"
+    v-on="scope.clear.events"
+  />
+</slot>
+```
+
+## open-indicator
+
+```vue
+<slot name="open-indicator" v-bind="scope.openIndicator">
+  <component
+    v-if="scope.openIndicator.shouldDisplay"
+    :is="scope.openIndicator.component"
+    v-bind="scope.openIndicator.attributes"
+  />
+</slot>
+```
+
+## spinner
+
+```vue
+<slot name="spinner" v-bind="scope.spinner">
+  <div :class="scope.spinner.bindings.class" v-show="mutableLoading">Loading...</div>
+</slot>
+```
+
+## option
+
+```vue
+<slot name="option" v-for="option in scopedOptions" v-bind="option">
+  <li v-bind="option.attributes" v-on="option.events">{{ option.label }}</li>
+</slot>
+```
+
+## no-options
+
+```vue
+<slot name="no-options">Sorry, no matching options.</slot>
+```
diff --git a/docs/guide/slots.md b/docs/guide/slots.md
index ad4710a..e81ebd7 100644
--- a/docs/guide/slots.md
+++ b/docs/guide/slots.md
@@ -1,13 +1,33 @@
-## Scoped Slots
+Vue Select offers a number of scoped slots that allow you to customize many parts of the
+component for your app. You can make small adjustments with slots, or you can swap out all elements
+of the default UI for your own. The slot API is the most powerful way to get things looking exactly
+the way you want them to.
 
-Vue Select offers a number of scoped slots that allow you to customize many parts of the 
-component for your app. You can make small adjustments with slots, or you can swap out all elements 
-of the default UI for your own.
+All the component scoped slots follow a similar pattern. Each slot is scoped with an object with at
+least two keys: `bindings` and `events`.
 
-All of Vue Selects scoped slots follow a similar pattern. Each slot is scoped with an object with at
-least two keys: `bindings` and `events`. 
+## `bindings {Object}`
 
-`bindings {Object}` Data that is bound to an element within the slot (HTML attributes, classes, etc)
-`events {Object}` Event handlers for elements within the slot
-    
+Data that is bound to an element within the slot (HTML attributes, classes, etc).
 
+## `events {Object}`
+
+Event handlers for elements within the slot, mapped to an object in the `{event: handler}` format.
+These can be conveniently bound to an element (like the search input for example) with
+`v-on="events"`. It's usually a good idea to check the slot definition to see if any event handlers
+need to be bound to implement functionality.
+
+You can also use the `events` object to modify default behaviour. Bind the specific handlers you want
+out of the object, or pass it to a function to add your own behaviour.
+
+## `option` slots
+
+There are many slots that receive an instance of the currently iterated `option` object.
+
+---
+
+### A Note on "Pure Slots"
+
+Similar to a pure function, any variables used within a Vue Select slot template are also bound to
+the slot itself. This ensures that slots have everything they require to modify the UI while
+retaining all default behaviour.