From 6e3943e10faf9aaf7ec08a15e5e237dfe470757f Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 14 Jun 2020 16:21:33 +0300
Subject: [PATCH 1/3] feat: added template refs

---
 src/.vuepress/config.js              |  5 +--
 src/api/composition-api.md           |  2 +-
 src/api/instance-properties.md       |  4 +--
 src/api/special-attributes.md        |  2 +-
 src/guide/component-template-refs.md | 46 ++++++++++++++++++++++++++++
 5 files changed, 53 insertions(+), 6 deletions(-)
 create mode 100644 src/guide/component-template-refs.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index b41320971d..5462d06178 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -25,7 +25,9 @@ const sidebar = {
         '/guide/component-props',
         '/guide/component-custom-events',
         '/guide/component-slots',
-        '/guide/component-provide-inject'
+        '/guide/component-provide-inject',
+        '/guide/component-dynamic-async',
+        '/guide/component-template-refs'
       ]
     },
     {
@@ -33,7 +35,6 @@ const sidebar = {
       collapsable: false,
       children: [
         '/guide/reactivity',
-        '/guide/component-dynamic-async',
         '/guide/optimizations',
         '/guide/change-detection'
       ]
diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index ef4843c068..1c8841ab58 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -291,7 +291,7 @@ const foo = inject<string>('foo') // string | undefined
 
 ## Template Refs
 
-When using the Composition API, the concept of [reactive refs](./refs-api.html#ref) and [template refs](TODO) are unified. In order to obtain a reference to an in-template element or component instance, we can declare a ref as usual and return it from `setup()`:
+When using the Composition API, the concept of [reactive refs](./refs-api.html#ref) and [template refs](../guide/component-template-refs.html) are unified. In order to obtain a reference to an in-template element or component instance, we can declare a ref as usual and return it from `setup()`:
 
 ```html
 <template>
diff --git a/src/api/instance-properties.md b/src/api/instance-properties.md
index 4a4a9bc805..f5c29fadd2 100644
--- a/src/api/instance-properties.md
+++ b/src/api/instance-properties.md
@@ -126,10 +126,10 @@
 
 - **Details:**
 
-An object of DOM elements and component instances, registered with [`ref` attributes](TODO).
+An object of DOM elements and component instances, registered with [`ref` attributes](../guide/component-template-refs.html).
 
 - **See also:**
-  - [Child Component Refs](TODO:refs)
+  - [Template refs](../guide/component-template-refs.html)
   - [Special Attributes - ref](./special-attributes.md#ref)
 
 ## $attrs
diff --git a/src/api/special-attributes.md b/src/api/special-attributes.md
index b136b9419d..7bd61335bd 100644
--- a/src/api/special-attributes.md
+++ b/src/api/special-attributes.md
@@ -49,7 +49,7 @@
 
   An important note about the ref registration timing: because the refs themselves are created as a result of the render function, you cannot access them on the initial render - they don't exist yet! `$refs` is also non-reactive, therefore you should not attempt to use it in templates for data-binding.
 
-- **See also:** [Child Component Refs](TODO-handling-edge-cases)
+- **See also:** [Child Component Refs](../guide/component-template-refs.html)
 
 ## is
 
diff --git a/src/guide/component-template-refs.md b/src/guide/component-template-refs.md
new file mode 100644
index 0000000000..b5cf55d28b
--- /dev/null
+++ b/src/guide/component-template-refs.md
@@ -0,0 +1,46 @@
+# Template refs
+
+> This page assumes you've already read the [Components Basics](component-basics.md). Read that first if you are new to components.
+
+Despite the existence of props and events, sometimes you might still need to directly access a child component in JavaScript. To achieve this you can assign a reference ID to the child component using the `ref` attribute. For example:
+
+```html
+<base-input ref="usernameInput"></base-input>
+```
+
+Now in the component where you've defined this `ref`, you can use:
+
+```js
+this.$refs.usernameInput
+```
+
+to access the `<base-input>` instance. This may be useful when you want to, for example, programmatically focus this input from a parent. In that case, the `<base-input>` component may similarly use a `ref` to provide access to specific elements inside it, such as:
+
+```html
+<input ref="input">
+```
+
+And even define methods for use by the parent:
+
+```js
+methods: {
+  // Used to focus the input from the parent
+  focus() {
+    this.$refs.input.focus()
+  }
+}
+```
+
+Thus allowing the parent component to focus the input inside `<base-input>` with:
+
+```js
+this.$refs.usernameInput.focus()
+```
+
+When `ref` is used together with `v-for`, the ref you get will be an array containing the child components mirroring the data source.
+
+::: warning
+`$refs` are only populated after the component has been rendered. It is only meant as an escape hatch for direct child manipulation - you should avoid accessing `$refs` from within templates or computed properties.
+:::
+
+**See also**: [Using template refs in Composition API](../api/composition-api.html#template-refs)

From dacac3ca1d4aecb9b17ec3c5d0be437716617a80 Mon Sep 17 00:00:00 2001
From: Natalia Tepluhina <tarya.se@gmail.com>
Date: Sun, 14 Jun 2020 19:31:26 +0300
Subject: [PATCH 2/3] Update src/guide/component-template-refs.md

Co-authored-by: Phan An <me@phanan.net>
---
 src/guide/component-template-refs.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/guide/component-template-refs.md b/src/guide/component-template-refs.md
index b5cf55d28b..2994d5f7f0 100644
--- a/src/guide/component-template-refs.md
+++ b/src/guide/component-template-refs.md
@@ -14,7 +14,7 @@ Now in the component where you've defined this `ref`, you can use:
 this.$refs.usernameInput
 ```
 
-to access the `<base-input>` instance. This may be useful when you want to, for example, programmatically focus this input from a parent. In that case, the `<base-input>` component may similarly use a `ref` to provide access to specific elements inside it, such as:
+to access the `<base-input>` instance. This may be useful when you want to, for example, programmatically set focus on this input from a parent. In that case, the `<base-input>` component may similarly use a `ref` to provide access to specific elements inside it, such as:
 
 ```html
 <input ref="input">

From 029388b1b64e38cfb3deaf882c4cdd2c8b2418e8 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Mon, 15 Jun 2020 16:52:24 +0300
Subject: [PATCH 3/3] fix: refactored template refs

---
 src/guide/component-template-refs.md | 41 ++++++++++++++--------------
 1 file changed, 21 insertions(+), 20 deletions(-)

diff --git a/src/guide/component-template-refs.md b/src/guide/component-template-refs.md
index b5cf55d28b..8cdeff5998 100644
--- a/src/guide/component-template-refs.md
+++ b/src/guide/component-template-refs.md
@@ -2,39 +2,40 @@
 
 > This page assumes you've already read the [Components Basics](component-basics.md). Read that first if you are new to components.
 
-Despite the existence of props and events, sometimes you might still need to directly access a child component in JavaScript. To achieve this you can assign a reference ID to the child component using the `ref` attribute. For example:
+Despite the existence of props and events, sometimes you might still need to directly access a child component in JavaScript. To achieve this you can assign a reference ID to the child component or HTML element using the `ref` attribute. For example:
 
 ```html
-<base-input ref="usernameInput"></base-input>
+<input ref="input" />
 ```
 
-Now in the component where you've defined this `ref`, you can use:
+This may be useful when you want to, for example, programmatically focus this input on component mount:
 
 ```js
-this.$refs.usernameInput
+const app = Vue.createApp({})
+
+app.component('base-input', {
+  template: `
+    <input ref="input" />
+  `,
+  methods: {
+    focusInput() {
+      this.$refs.input.focus()
+    }
+  },
+  mounted() {
+    this.focusInput()
+  }
+})
 ```
 
-to access the `<base-input>` instance. This may be useful when you want to, for example, programmatically focus this input from a parent. In that case, the `<base-input>` component may similarly use a `ref` to provide access to specific elements inside it, such as:
+Also, you can add another `ref` to the component itself and use it to trigger `focusInput` event from the parent component:
 
 ```html
-<input ref="input">
-```
-
-And even define methods for use by the parent:
-
-```js
-methods: {
-  // Used to focus the input from the parent
-  focus() {
-    this.$refs.input.focus()
-  }
-}
+<base-input ref="usernameInput"></base-input>
 ```
 
-Thus allowing the parent component to focus the input inside `<base-input>` with:
-
 ```js
-this.$refs.usernameInput.focus()
+this.$refs.usernameInput.focusInput()
 ```
 
 When `ref` is used together with `v-for`, the ref you get will be an array containing the child components mirroring the data source.