Merge branch 'master' into 3.0

# Conflicts:
#	package.json

Author: marshallswain

docs/.vuepress/config.js

@@ -1,6 +1,7 @@
 module.exports = {
   title: 'FeathersVuex',
   description: 'Integration of FeathersJS, Vue, and Nuxt for the artisan developer',
+  head: [['link', { rel: 'icon', href: '/favicon.ico' }]],
   theme: 'default-prefers-color-scheme',
   themeConfig: {
     repo: 'feathersjs-ecosystem/feathers-vuex',
@@ -24,4 +25,4 @@ module.exports = {
       updatePopup: true
     }
   }
-}
+}

docs/.vuepress/public/favicon.ico

@@ -112,6 +112,17 @@ build: {
 }
 ```
 
+## Vue DevTools
+
+Since Feathers-Vuex extensively uses Vuex under the hood, you'll want to make sure your VueJS developer tools are up to date AND setup properly.  Specifically, the "New Vuex Backend" needs to be enabled.  To setup the devtools
+
+1. Open the Vue tab of the developer tools while viewing your Vue project in the browser.
+1. Go to the Settings panel.
+1. Enable the new Vuex backend:
+
+![New Vuex Backend in Vue DevTools](/img/devtools.jpg)
+
+When the above setting is not enabled, the Vue Devtools will likely hang when you start working on a large project.
 
 ## Setup
 

docs/.vuepress/public/img/devtools.jpg

@@ -46,8 +46,12 @@ The `FeathersVuexFormWrapper` component uses the "clone and commit" pattern to c
 </template>
 
 <script>
+
+import { FeathersVuexFormWrapper } from 'feathers-vuex'
+
 export default {
   name: 'MyComponent',
+  components: { FeathersVuexFormWrapper },
   props: {
     currentItem: {
       type: Object,
@@ -85,8 +89,12 @@ Here's another example of how you could use the form wrapper to both save the fo
 </template>
 
 <script>
+
+import { FeathersVuexFormWrapper } from 'feathers-vuex'
+
 export default {
   name: 'MyComponent',
+  components: { FeathersVuexFormWrapper },
   props: {
     currentItem: {
       type: Object,
@@ -117,4 +125,128 @@ The default slot contains only four attributes.  The `clone` data can be passed
 - `clone`: {Object} The cloned record.  Each record in the store can have a single clone.  The clones are stored on the service's model class, by default.
 - `save`: {Function} When called, it commits the data and saves the record (with eager updating, by default.  See the `eager` prop.)  The save method calls `instance.save()`, internally, so you can pass a params object, if needed.
 - `reset`: {Function} When called, the clone data will be reset back to the data that is currently found in the store for the same record.
-- `remove`: {Function} When called, it removes the record from the API server and the Vuex store.
+- `remove`: {Function} When called, it removes the record from the API server and the Vuex store.
+
+## Example Usage: CRUD Form
+
+### TodoView
+
+It's a pretty common scenario to have the same form handle editing and creating data.  Below is a basic example of how you could use the FeathersVuexFormWrapper for this.  A few things to notice about the example:
+
+1. It uses a `Todo` Model class to create and edit todos.  The `$FeathersVuex` object is available on `this` only when the [Feathers-Vuex Vue plugin](./vue-plugin.md) is used.
+2. It assumes that you have a route setup with an `:id` parameter.
+3. It assumes that the data has a MongoDB-style `_id` property, where an SQL-based service would probably use `id`.
+
+```vue
+<template>
+  <FeathersVuexFormWrapper :item="item" watch>
+    <template v-slot="{ clone, save, reset, remove }">
+      <TodoEditor
+        :item="clone"
+        @save="save().then(handleSaveResponse)"
+        @reset="reset"
+        @remove="remove"
+      ></TodoEditor>
+    </template>
+  </FeathersVuexFormWrapper>
+</template>
+
+<script>
+import { FeathersVuexFormWrapper } from 'feathers-vuex'
+import TodoEditor from './TodoEditor.vue'
+
+export default {
+  name: 'TodoView',
+  components: {
+    FeathersVuexFormWrapper,
+    TodoEditor
+  },
+  props: {
+    currentItem: {
+      type: Object,
+      required: true
+    }
+  },
+  computed: {
+    id() {
+      return this.$route.params.id
+    },
+    // Returns a new Todo if the route `id` is 'new', or returns an existing Todo.
+    item() {
+      const { Todo } = this.$FeathersVuex.api
+
+      return this.id === 'new' ? new Todo() : Todo.getFromStore(this.id)
+    },
+  },
+  watch: {
+    id: {
+      handler(val) {
+        // Early return if the route `:id` is 'new'
+        if (val === 'new') {
+          return
+        }
+        const { Todo } = this.$FeathersVuex.api
+        const existingRecord = Todo.getFromStore(val)
+
+        // If the record doesn't exist, fetch it from the API server
+        // The `item` getter will automatically update after the data arrives.
+        if (!existingRecord) {
+          Todo.get(val)
+        }
+      },
+      // We want the above handler handler to run immediately when the component is created.
+      immediate: true
+    }
+  },
+  methods: {
+    handleSaveReponse(savedTodo) {
+      // Redirect to the newly-saved item
+      if (this.id === 'new') {
+        this.$router.push({ params: { id: savedTodo._id } })
+      }
+    }
+  }
+}
+</script>
+```
+
+
+### TodoEditor
+
+Next let's look at a minimal example of a 'TodoEditor' component which is a child of the `FeathersVuexFormWrapper` in the above example.  A few things to notice about the below `TodoEditor` component:
+
+1. It's minimal on purpose to show you the important parts of working with the `FeathersVuexFormWrapper`.
+1. It emits the `save`, `reset`, and `remove` events, which are connected to the `FeathersVuexFormWrapper` in the above code snippet.
+1. It's not styled to keep it simple.  You'll probably want to add some styles.  ;)
+1. The Delete button immediately emits remove, so the instance will be deleted immediately.  You probably want, instead, to show a prompt or confirmation dialog to ask the user to confirm deletion.
+1. This is HTML, so the button `type` is important.  If you forget to add `type="button"` to a button, it will default to `type="submit"`.  Clicking the button would submit the form and call the `@submit.prevent` handler on the `<form>` element.  This even applies to buttons inside child components of the form.  You definitely want to remember to put `type` attributes on all of your buttons.
+
+```vue
+<template>
+  <form @submit.prevent="$emit('save')">
+    <input type="checkbox" v-model="item.isComplete" />
+    <input type="text" v-model="item.description" />
+
+    <!-- Submits the form, see the @submit handler, above -->
+    <button type="submit">Save</button>
+
+    <!-- Emitting reset will restore the item back to the stored version. -->
+    <button type="button" @click="$emit('reset')>Reset</button>
+
+    <!-- Delete's the instance -->
+    <button type="button" @click="$emit('remove')>Delete</button>
+  </form>
+</template>
+
+<script>
+export default {
+  name: 'TodoEditor',
+  props: {
+    item: {
+      type: Object,
+      required: true
+    }
+  }
+}
+</script>
+```

docs/api-overview.md

@@ -113,23 +113,60 @@ created () {
 
 `instanceDefaults(data, { store, Models })`
 
+The `instanceDefaults` API was created in version 1.7 to prevent requiring to specify data for new instances created throughout the app.  Depending on the complexity of the service's "business logic", it can save a lot of boilerplate.  Notice that it is similar to the `setupInstance` method added in 2.0.  The instanceDefaults method should ONLY be used to return default values for a new instance.  Use `setupInstance` to handle other transformations on the data.
+
 Starting with version 2.0, `instanceDefaults` must be provided as a function.  The function will be called with the following arguments and should return an object of default properties for new instances.
 
 - `data {Object}` - The instance data
 - An `utils` object containing these props:
   - `store` - The vuex store
-  - `Models {Object}` The `globalModels` object, which is the same as you'll find inside a component at `this.$FeathersVuex`.
+  - `models {Object}` The `globalModels` object, which is the same as you'll find inside a component at `this.$FeathersVuex`.
+
+As an example, a User model class might look like this:
+
+```js
+instanceDefaults(data, { store, models }) {
+  return {
+    firstName: '',
+    lastName: '',
+    email: '',
+    password: '',
+    isAdmin: false
+  }
+}
+```
+
+With the above attributes in place, you no longer have to manually specify any of the listed attributes.  You can, however, provided data to replace them.  Calling `new User({ firstName: 'Marshall' })` will create the instance with the `firstName` filled in, already.
+
+One important note, the `isAdmin` attribute is specified in the above example in order to allow immediate binding in a form.  You would pretty much NEVER allow specifying `isAdmin` from the client and storing it on the server.  Attributes related to roles and app security should pretty much ALWAYS be written in hooks on the API server.
 
 ### setupInstance  <Badge text="2.0.0+" />
 
 `setupInstance(data, { store, Models })`
 
-A new `setupinstance` class method is now available in version 2.0.  The function will be called with the following arguments and should return an object of default properties for new instances.
+A new `setupinstance` class method is now available in version 2.0.  This method allows you to transform the data and setup the final instance based on incoming data.  For example, you can access the `models` object to reference other service Model classes and create data associations.
+
+The function will be called with the following arguments and should return an object of default properties for new instances.
 
 - `data {Object}` - The instance data
-- An `utils` object containing these props:
+- A `utils` object containing these props:
   - `store` - The vuex store
-  - `Models {Object}` The `globalModels` object, which is the same as you'll find inside a component at `this.$FeathersVuex`.
+  - `models {Object}` The `globalModels` object, which is the same as you'll find inside a component at `this.$FeathersVuex`.
+
+For an example of how you might use `setupInstance`, suppose we have two services: Users and Posts.  Assume that the API request to get a user includes their `posts`, already populated on the data.  The `instanceDefaults` allows us to convert the array of `posts` into an array of `Post` instances.
+
+```js
+// The setupInstance method on an imaginary User model.
+setupInstance(data, { store, models }) {
+  if (data.posts) {
+    // Turn posts into an array of Post instances
+    data.posts = data.posts.map(p => new models.Todo(p))
+  }
+  return data
+}
+```
+
+With the above `setupInstance` method in place, each `User` instance now stores a direct reference to the `Post` records in the store.
 
 ### on <Badge text="2.3.0+" />
 
@@ -165,7 +202,7 @@ export default {
 }
 ```
 
-Since they have all of the EventEmitter methods, Model classes can be used as a data-layer Event Bus.  You can even use custom methods:
+Since they have all of the EventEmitter methods, Model classes can be used as a data-layer Event Bus.  You can even use custom event names:
 
 ```js
 const { Todo } = this.$FeathersVuex.api