Merge branch 'master' of github.com:vuejs/docs-next

Author: NataliaTepluhina

src/guide/component-dynamic-async.md

@@ -1,6 +1,6 @@
 # Dynamic & Async Components
 
-> This page assumes you've already read the [Components Basics](components.md). Read that first if you are new to components.
+> This page assumes you've already read the [Components Basics](component-basics.md). Read that first if you are new to components.
 
 ## Dynamic Components with `keep-alive`
 

src/guide/composition-api-introduction.md

@@ -35,7 +35,7 @@ export default {
   methods: {
     getUserRepositories () {
       // using `this.user` to fetch user repositories
-    }, // 2
+    }, // 1
     updateFilters () { ... }, // 3
   },
   mounted () {

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 provided 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>
 ```
-
-:::

src/guide/contributing/writing-guide.md

@@ -58,6 +58,7 @@ Writing documentation is an exercise in empathy. We're not describing an objecti
 - **Avoid abbreviations** in writing and code examples (e.g. `attribute` is better than `attr`, `message` is better than `msg`), unless you are specifically referencing an abbreviation in an API (e.g. `$attrs`). Abbreviation symbols included on standard keyboards (e.g. `@`, `#`, `&`) are OK.
 - **When referencing a directly following example, use a colon (`:`) to end a sentence**, rather than a period (`.`).
 - **Use the Oxford comma** (e.g. "a, b, and c" instead of "a, b and c"). ![Why the Oxford comma is important](https://raw.githubusercontent.com/vuejs/vuejs.org/master/src/images/oxford-comma.jpg)
+  - Source: [The Serial (Oxford) Comma: When and Why To Use It](https://www.inkonhand.com/2015/10/the-serial-oxford-comma-when-and-why-to-use-it/)
 - **When referencing the name of a project, use the name that project refers to itself as.** For example, "webpack" and "npm" should both use lowercase as that's how their documentation refers to them.
 - **Use Title Case for headings** - at least for now, since it's what we use through the rest of the docs. There's research suggesting that sentence case (only first word of the heading starts with a capital) is actually superior for legibility and also reduces the cognitive overhead for documentation writers, since they don't have to try to remember whether to capitalize words like "and", "with", and "about".
 - **Don't use emojis (except in discussions).** Emojis are cute and friendly, but they can be a distraction in documentation and some emoji even convey different meanings in different cultures.

src/guide/migration/introduction.md

@@ -8,6 +8,11 @@ Possibly the biggest change is our new [Composition API](/guide/composition-api-
 
 ## Overview
 
+<br>
+<iframe src="https://player.vimeo.com/video/440868720" width="640" height="360" frameborder="0" allow="autoplay; fullscreen" allowfullscreen></iframe>
+
+Start learning Vue 3 at [Vue Mastery](https://www.vuemastery.com/courses-path/vue3).
+
 ### New Features
 
 Some of the new features to keep an eye on in Vue 3 include: