docs (#391): update provide inject in composition api with enhanced reactivity (#396)

* docs: use maps example in provide inject composition

* docs: update code sample to show object

* docs (#391): enhance provide inject reactivity section

* docs: update disclaimer for provide inject composition api

* docs: fix imports

* docs: remove unnecessary qualifier

* docs: fix grammar in disclaimer

* docs: integrate tip into content

Author: bencodezen

src/guide/composition-api-provide-inject.md

@@ -1,121 +1,280 @@
 # Provide / Inject
 
-> This guide assumes that you have already read the [Composition API Introduction](composition-api-introduction.html) and [Reactivity Fundamentals](reactivity-fundamentals.html). Read that first if you are new to Composition API.
+> This guide assumes that you have already read [Provide / Inject](component-provide-inject.html), [Composition API Introduction](composition-api-introduction.html), and [Reactivity Fundamentals](reactivity-fundamentals.html).
 
 We can use [provide / inject](component-provide-inject.html) with the Composition API as well. Both can only be called during [`setup()`](composition-api-setup.html) with a current active instance.
 
-For example, if we want to provide a book name on the root component and inject it on the child component:
+## Scenario Background
 
-```js
-import { provide, inject } from 'vue'
+Let's assume that we want to rewrite the following code, which contains a `MyMap` component that provides a `MyMarker` component with the user's location, using the Composition API.
 
-const RootComponent = {
+```vue
+<!-- src/components/MyMap.vue -->
+<template>
+  <MyMarker />
+</template>
+
+<script>
+import MyMarker from './MyMarker.vue'
+
+export default {
+  components: {
+    MyMarker
+  },
+  provide: {
+    location: 'North Pole',
+    geolocation: {
+      longitude: 90,
+      latitude: 135
+    }
+  }
+}
+</script>
+```
+
+```vue
+<!-- src/components/MyMarker.vue -->
+<script>
+export default {
+  inject: ['location', 'longitude', 'latitude']
+}
+</script>
+```
+
+## Using Provide
+
+When using `provide` in `setup()`, we start by explicitly importing the method from `vue`. This allows us to define each property with its own invocation of `provide`.
+
+The `provide` function allows you to define the property through two parameters:
+
+1. The property's name (`<String>` type)
+2. The property's value
+
+Using our `MyMap` component, our provided values can be refactored as the following:
+
+```vue{7,14-20}
+<!-- src/components/MyMap.vue -->
+<template>
+  <MyMarker />
+</template>
+
+<script>
+import { provide } from 'vue'
+import MyMarker from './MyMarker.vue
+
+export default {
+  components: {
+    MyMarker
+  },
   setup() {
-    provide('book', 'Vue 3 guide')
+    provide('location', 'North Pole')
+    provide('geolocation', {
+      longitude: 90,
+      latitude: 135
+    })
   }
 }
+</script>
+```
+
+## Using Inject
+
+When using `inject` in `setup()`, we also need to explicitly import it from `vue`. Once we do so, this allows us to invoke it to define how we want to expose it to our component.
+
+The `inject` function takes two parameters:
 
-const MyBook = {
+1. The name of the property to inject
+2. A default value (**Optional**)
+
+Using our `MyMarker` component, we can refactor it with the following code:
+
+```vue{3,6-14}
+<!-- src/components/MyMarker.vue -->
+<script>
+import { inject } from 'vue'
+
+export default {
   setup() {
-    const book = inject(
-      'book',
-      'Eloquent Javascript' /* optional default value */
-    )
+    const userLocation = inject('location', 'The Universe')
+    const userGeolocation = inject('geolocation')
+
     return {
-      book
+      userLocation,
+      userGeolocation
     }
   }
 }
+</script>
 ```
 
-`inject` accepts an optional default value as the 2nd argument. If a default value is not provided and the property is not found on the provide context, `inject` returns `undefined`.
+## Reactivity
+
+### Adding Reactivity
+
+To add reactivity between provided and injected values, we can use a [ref](reactivity-fundamentals.html#creating-standalone-reactive-values-as-refs) or [reactive](reactivity-fundamentals.html#declaring-reactive-state) when providing a value.
+
+Using our `MyMap` component, our code can be updated as follows:
 
-If we need to provide or inject multiple values, we can do this with a subsequent call of `provide` or `inject` respectively:
+```vue{7,15-22}
+<!-- src/components/MyMap.vue -->
+<template>
+  <MyMarker />
+</template>
 
-```js{5-6,12-16}
-import { provide, inject } from 'vue'
+<script>
+import { provide, reactive, ref } from 'vue'
+import MyMarker from './MyMarker.vue
 
-const RootComponent = {
+export default {
+  components: {
+    MyMarker
+  },
   setup() {
-    provide('book', 'Vue 3 guide')
-    provide('year', '2020')
+    const location = ref('North Pole')
+    const geolocation = reactive({
+      longitude: 90,
+      latitude: 135
+    })
+
+    provide('location', location)
+    provide('geolocation', geolocation)
   }
 }
+</script>
+```
+
+Now, if anything changes in either property, the `MyMarker` component will automatically be updated as well!
+
+### Mutating Reactive Properties
+
+When using reactive provide / inject values, **it is recommended to keep any mutations to reactive properties inside of the _provider_ whenever possible**.
+
+For example, in the event we needed to change the user's location, we would ideally do this inside of our `MyMap` component.
+
+```vue{28-32}
+<!-- src/components/MyMap.vue -->
+<template>
+  <MyMarker />
+</template>
 
-const MyBook = {
+<script>
+import { provide, reactive, ref } from 'vue'
+import MyMarker from './MyMarker.vue
+
+export default {
+  components: {
+    MyMarker
+  },
   setup() {
-    const book = inject(
-      'book',
-      'Eloquent Javascript' /* optional default value */
-    )
-    const year = inject('year')
+    const location = ref('North Pole')
+    const geolocation = reactive({
+      longitude: 90,
+      latitude: 135
+    })
+
+    provide('location', location)
+    provide('geolocation', geolocation)
 
     return {
-      book,
-      year
+      location
+    }
+  },
+  methods: {
+    updateLocation() {
+      this.location = 'South Pole'
     }
   }
 }
+</script>
 ```
 
-## Injection Reactivity
-
-To retain reactivity between provided and injected values, we can use a [ref](reactivity-fundamentals.html#creating-standalone-reactive-values-as-refs) or [reactive](reactivity-fundamentals.html#declaring-reactive-state) when providing a value:
+However, there are times where we need to update the data inside of the component where the data is injected. In this scenario, we recommend providing a method that is responsible for mutating the reactive property.
 
-```js
-import { ref, reactive } from 'vue'
+```vue{21-23,27}
+<!-- src/components/MyMap.vue -->
+<template>
+  <MyMarker />
+</template>
 
-// in provider
-setup() {
-  const book = reactive({
-    title: 'Vue 3 Guide',
-    author: 'Vue Team'
-  })
-  const year = ref('2020')
+<script>
+import { provide, reactive, ref } from 'vue'
+import MyMarker from './MyMarker.vue
 
-  provide('book', book)
-  provide('year', year)
-}
+export default {
+  components: {
+    MyMarker
+  },
+  setup() {
+    const location = ref('North Pole')
+    const geolocation = reactive({
+      longitude: 90,
+      latitude: 135
+    })
 
-// in consumer
-setup() {
-  const book = inject('book')
-  const year = inject('year')
+    const updateLocation = () => {
+      location.value = 'South Pole'
+    }
 
-  return { book, year }
+    provide('location', location)
+    provide('geolocation', geolocation)
+    provide('updateLocation', updateLocation)
+  }
 }
+</script>
 ```
 
-Now, when either `book` or `year` are changed on the _provider_ component, we can observe them changing on the component where they are injected.
+```vue{9,14}
+<!-- src/components/MyMarker.vue -->
+<script>
+import { inject } from 'vue'
+
+export default {
+  setup() {
+    const userLocation = inject('location', 'The Universe')
+    const userGeolocation = inject('geolocation')
+    const updateUserLocation = inject('updateUserLocation')
 
-::: warning
-We don't recommend mutating a reactive property where it's injected as it's breaking Vue one-direction data flow. Instead, try to either mutate values where they are _provided_ or provide a method to mutate them
+    return {
+      userLocation,
+      userGeolocation,
+      updateUserLocation
+    }
+  }
+}
+</script>
+```
 
-```js
-import { ref, reactive } from 'vue'
+Finally, we recommend using `readonly` on provdided property if you want to ensure that the data passed through `provide` cannot be mutated by the injected component.
 
-// in provider
-setup() {
-  const book = reactive({
-    title: 'Vue 3 Guide',
-    author: 'Vue Team'
-  })
+```vue{7,25-26}
+<!-- src/components/MyMap.vue -->
+<template>
+  <MyMarker />
+</template>
 
-  function changeBookName() {
-    book.title = 'Vue 3 Advanced Guide'
-  }
+<script>
+import { provide, reactive, readonly, ref } from 'vue'
+import MyMarker from './MyMarker.vue
 
-  provide('book', book)
-  provide('changeBookName', changeBookName)
-}
+export default {
+  components: {
+    MyMarker
+  },
+  setup() {
+    const location = ref('North Pole')
+    const geolocation = reactive({
+      longitude: 90,
+      latitude: 135
+    })
 
-// in consumer
-setup() {
-  const book = inject('book')
-  const changeBookName = inject('changeBookName')
+    const updateLocation = () => {
+      location.value = 'South Pole'
+    }
 
-  return { book, changeBookName }
+    provide('location', readonly(location))
+    provide('geolocation', readonly(geolocation))
+    provide('updateLocation', updateLocation)
+  }
 }
+</script>
 ```
-
-:::