From f06663845d731ad767e53047a81eabb611b1bea5 Mon Sep 17 00:00:00 2001
From: Stas Lashmanov <stasvarenkin@gmail.com>
Date: Thu, 27 Feb 2020 02:18:06 +0300
Subject: [PATCH 1/8] Add component's public API RFC

---
 active-rfcs/0000-component's-public-api.md | 307 +++++++++++++++++++++
 1 file changed, 307 insertions(+)
 create mode 100644 active-rfcs/0000-component's-public-api.md

diff --git a/active-rfcs/0000-component's-public-api.md b/active-rfcs/0000-component's-public-api.md
new file mode 100644
index 00000000..5a44e60f
--- /dev/null
+++ b/active-rfcs/0000-component's-public-api.md
@@ -0,0 +1,307 @@
+- Start Date: (fill me in with today's date, 2020-02-27)
+- Target Major Version: 3.x
+- Reference Issues: (fill in existing related issues, if any)
+- Implementation PR: (leave this empty)
+
+# Summary
+
+Use `provide` to define component's public API available for parent components via `refs`.
+
+# Basic example
+
+Right now you can access the whole component's context without any limitations when using `refs`.
+
+```html
+<template>
+  <div />
+</template>
+
+<script>
+  export default {
+    name: 'Foo',
+    methods: {
+      someMethod() {}
+    }
+  }
+</script>
+```
+
+```html
+<template>
+  <Foo ref="foo" />
+</template>
+
+<script>
+  export default {
+    name: 'Bar',
+    mounted() {
+      this.$refs.foo.someMethod() // you can access anything on the context
+    }
+  }
+</script>
+```
+
+After the change you'll be required to expose your data and methods explicitly.
+
+```html
+<template>
+  <div />
+</template>
+
+<script>
+  export default {
+    name: 'Foo',
+    provide() {
+      const { someMethod } = this;
+      return {
+        someMethod,
+      }
+    },
+    methods: {
+      someMethod() {},
+      anotherMethod() {},
+    }
+  }
+</script>
+```
+
+```html
+<template>
+  <Foo ref="foo" />
+</template>
+
+<script>
+  export default {
+    name: 'Bar',
+    mounted() {
+      this.$refs.foo.someMethod() // exposed
+      this.$refs.foo.anotherMethod() // error, not exposed
+    }
+  }
+</script>
+```
+
+# Motivation
+
+Right now component's context is free to access by anyone and that brings up a number of issues:
+
+1. You can not guarantee consistent component's behaviour due to external modifications. You can modify components data and won't be able to tell where that change came from.
+2. There's no contract between receiver and provider components. This could lead to refactoring problems when there's an unused method within the component, but it's required by another component and there's no easy way to tell that.
+3. No clear separation of data that is required by the component itself and other components.
+
+To fix these issues components would be required to explicitly declare their public interface.
+
+# Detailed design
+
+Components should not be able to directly access other components context anymore. To declare component's public interface use `provide` and pass any data that should be exposed. The object returned in `provide` would serve as a main access point for the accessor component. To eliminate conflicts and provide better cohesion use `Symbol` for exposed data property names.
+
+A component with such an interface could look like this:
+
+```html
+<template>
+  <input ref="input">
+</template>
+
+<script>
+  export const FOCUS_INPUT = Symbol()
+  
+  export default {
+    name: 'MyInput',
+    provide() {
+      const { focusInput } = this
+      return {
+        [FOCUS_INPUT]: focusInput
+      }
+    },
+    methods: {
+      focusInput() {
+        this.$refs.input.focus()
+      }
+    }
+  }
+</script>
+```
+
+This interface could be utilized as following:
+
+```html
+<template>
+  <MyInput :ref="myInput" />
+</template>
+
+<script>
+  import { FOCUS_INPUT } from 'MyInput.vue'
+  
+  export default {
+    mounted() {
+      this.$refs.myInput[FOCUS_INPUT]()
+    }
+  }
+</script>
+```
+
+To expose refs use `mounted` hook and object as a wrapper to preserve reactivity.
+
+```html
+<template>
+  <input ref="input">
+</template>
+
+<script>
+  export const INPUT_EXPOSED = Symbol()
+  
+  export default {
+    provide() {
+      const { exposed } = this
+      return {
+        [INPUT_EXPOSED]: exposed
+      }
+    },
+    data() {
+      return {
+        exposed: {
+          inputRef: null
+        }
+      }
+    },
+    mounted() {
+      this.exposed.inputRef = this.$refs.input
+    }
+  }
+</script>
+```
+
+Or function refs:
+
+```html
+<template>
+  <input :ref="(input) => exposed.inputRef = input">
+</template>
+
+<script>
+  export const INPUT_EXPOSED = Symbol()
+  
+  export default {
+    provide() {
+      const { exposed } = this
+      return {
+        [INPUT_EXPOSED]: exposed
+      }
+    },
+    data() {
+      return {
+        exposed: {
+          inputRef: null
+        }
+      }
+    },
+  }
+</script>
+```
+
+Example using Composition API:
+
+```html
+<template>
+  <input ref="inputRef">
+</template>
+
+<script>
+  import { ref } from 'vue'
+  export const INPUT_REF = Symbol()
+  
+  export default {
+    name: 'MyInput',
+    setup() {
+      const inputRef = ref(null)
+      provide(INPUT_REF, inputRef)
+
+      return {
+        inputRef
+      }
+    }
+  }
+</script>
+```
+
+You'll then be able to use it as a ref:
+
+```html
+<template>
+  <MyInput ref="myInput" />
+</template>
+
+<script>
+  import { INPUT_REF } from 'MyInput.vue'
+  
+  export default {
+    setup() {
+      const myInput = ref(null)
+      onMounted(() => {
+        console.log(myInput.value[INPUT_REF].value)
+      })
+
+      return {
+        myInput
+      }
+    }
+  }
+</script>
+```
+
+# Drawbacks
+
+* Should be triggered after data init, `refs` then would require a lot of fiddling around to preserve reactivity (wrapping exposed values inside an object at a minimum)
+* Provides value down the render tree as a side-effect, which may not be the desired behaviour
+
+# Alternatives
+
+* Use dedicated hook instead of `provide` but with exactly the same API. Could be called `expose`.
+
+  **Pros**:
+
+  * Does not cause conflicts with other provisions
+  * Clear separation of concerns
+
+  **Cons**:
+
+  * One more option to learn about
+  * Could be confusing to pick one between the `provide` and `expose`
+  * Does not fix the issue with `refs`
+
+* Use events to expose your component's public interface:  
+  ```html
+  <template>
+    <input ref="input">
+  </template>
+
+  <script>    
+    export default {
+      mounted() {
+        const exposed = {
+          focusInput: () => {
+            this.$refs.input.focus()
+          }
+        };
+        this.$emit('ready', exposed);
+      }
+    }
+  </script>
+  ```
+
+  **Pros**:
+
+  * Does not require any API change
+  * Easy to implement
+  * Fixes `refs` issue
+
+  **Cons**:
+
+  * Can not be enforced by the framework (unless context is always unavailable in refs)
+  * Forces to be extra careful with context
+  * Creates an unnecessary data flow
+
+
+# Adoption strategy
+
+Components containing any data required by the parent component via `refs` would be required to explicitly declare their public interface.
\ No newline at end of file

From 08f036ef78f98311ad0719978a332b0750f0e637 Mon Sep 17 00:00:00 2001
From: Stas Lashmanov <stasvarenkin@gmail.com>
Date: Thu, 27 Feb 2020 03:15:20 +0300
Subject: [PATCH 2/8] Add alternative ref example

---
 active-rfcs/0000-component's-public-api.md | 39 ++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/active-rfcs/0000-component's-public-api.md b/active-rfcs/0000-component's-public-api.md
index 5a44e60f..fa70aa9a 100644
--- a/active-rfcs/0000-component's-public-api.md
+++ b/active-rfcs/0000-component's-public-api.md
@@ -199,6 +199,45 @@ Or function refs:
 </script>
 ```
 
+Alternative way of accessing refs:
+
+```html
+<template>
+  <input ref="input">
+</template>
+
+<script>
+  export const GET_INPUT_REF = Symbol()
+  
+  export default {
+    name: 'MyInput',
+    provide() {
+      return {
+        [GET_INPUT_REF]: () => {
+          return this.$refs.input
+        }
+      }
+    },
+  }
+</script>
+```
+
+```html
+<template>
+  <MyInput ref="input">
+</template>
+
+<script>
+  import { GET_INPUT_REF } from 'MyInput.vue'
+  
+  export default {
+    mounted() {
+      console.log(this.$refs.input[GET_INPUT_REF]())
+    }
+  }
+</script>
+```
+
 Example using Composition API:
 
 ```html

From 508b4ff03ae5b2a391f28c69e6356f1e4e751958 Mon Sep 17 00:00:00 2001
From: Stas Lashmanov <stasvarenkin@gmail.com>
Date: Thu, 27 Feb 2020 03:27:06 +0300
Subject: [PATCH 3/8] Typo

---
 active-rfcs/0000-component's-public-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/active-rfcs/0000-component's-public-api.md b/active-rfcs/0000-component's-public-api.md
index fa70aa9a..0f2ba91d 100644
--- a/active-rfcs/0000-component's-public-api.md
+++ b/active-rfcs/0000-component's-public-api.md
@@ -1,4 +1,4 @@
-- Start Date: (fill me in with today's date, 2020-02-27)
+- Start Date: 2020-02-27
 - Target Major Version: 3.x
 - Reference Issues: (fill in existing related issues, if any)
 - Implementation PR: (leave this empty)

From 3cc7f14e8c5c6b15bbbbaccb08399cba43a64414 Mon Sep 17 00:00:00 2001
From: Stas Lashmanov <stasvarenkin@gmail.com>
Date: Thu, 27 Feb 2020 03:56:25 +0300
Subject: [PATCH 4/8] Add performance penalty to drawbacks section

---
 active-rfcs/0000-component's-public-api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/active-rfcs/0000-component's-public-api.md b/active-rfcs/0000-component's-public-api.md
index 0f2ba91d..f32facbf 100644
--- a/active-rfcs/0000-component's-public-api.md
+++ b/active-rfcs/0000-component's-public-api.md
@@ -292,6 +292,7 @@ You'll then be able to use it as a ref:
 
 * Should be triggered after data init, `refs` then would require a lot of fiddling around to preserve reactivity (wrapping exposed values inside an object at a minimum)
 * Provides value down the render tree as a side-effect, which may not be the desired behaviour
+* This could cause performance penalty if any injections are used since we have to cycle through every provision in the vnode tree from bottom to top
 
 # Alternatives
 

From 793f37d3e336db0cb85a60f8f13a02d28e405ca3 Mon Sep 17 00:00:00 2001
From: Stas Lashmanov <stasvarenkin@gmail.com>
Date: Fri, 28 Feb 2020 03:09:28 +0300
Subject: [PATCH 5/8] Introduce expose api, scrap out provide overload

---
 active-rfcs/0000-component's-public-api.md | 282 +++++++++++++--------
 1 file changed, 171 insertions(+), 111 deletions(-)

diff --git a/active-rfcs/0000-component's-public-api.md b/active-rfcs/0000-component's-public-api.md
index f32facbf..12395110 100644
--- a/active-rfcs/0000-component's-public-api.md
+++ b/active-rfcs/0000-component's-public-api.md
@@ -5,22 +5,22 @@
 
 # Summary
 
-Use `provide` to define component's public API available for parent components via `refs`.
+Introduce a new `expose` option to declare component's public API available for parent components via `refs`. Restrict access to component's context by default.
 
 # Basic example
 
-Right now you can access the whole component's context without any limitations when using `refs`.
+At the moment you can access the whole component's context without any limitations when using `refs`.
 
 ```html
 <template>
-  <div />
+  <input ref="input">
 </template>
 
 <script>
   export default {
-    name: 'Foo',
+    name: 'MyInput',
     methods: {
-      someMethod() {}
+      focus() { this.$refs.input.focus() }
     }
   }
 </script>
@@ -28,14 +28,14 @@ Right now you can access the whole component's context without any limitations w
 
 ```html
 <template>
-  <Foo ref="foo" />
+  <MyInput ref="input" />
 </template>
 
 <script>
   export default {
-    name: 'Bar',
+    name: 'Parent',
     mounted() {
-      this.$refs.foo.someMethod() // you can access anything on the context
+      this.$refs.input.focus() // you can access anything on the context
     }
   }
 </script>
@@ -45,21 +45,16 @@ After the change you'll be required to expose your data and methods explicitly.
 
 ```html
 <template>
-  <div />
+  <input ref="input">
 </template>
 
 <script>
   export default {
-    name: 'Foo',
-    provide() {
-      const { someMethod } = this;
-      return {
-        someMethod,
-      }
-    },
+    name: 'MyInput',
+    expose: ['focus'],
     methods: {
-      someMethod() {},
-      anotherMethod() {},
+      focus() { this.$refs.input.focus() },
+      blur() { this.$refs.input.blur() },
     }
   }
 </script>
@@ -67,15 +62,15 @@ After the change you'll be required to expose your data and methods explicitly.
 
 ```html
 <template>
-  <Foo ref="foo" />
+  <MyInput ref="input" />
 </template>
 
 <script>
   export default {
-    name: 'Bar',
+    name: 'Parent',
     mounted() {
-      this.$refs.foo.someMethod() // exposed
-      this.$refs.foo.anotherMethod() // error, not exposed
+      this.$refs.input.focus() // exposed
+      this.$refs.input.blue() // error, not exposed
     }
   }
 </script>
@@ -93,48 +88,147 @@ To fix these issues components would be required to explicitly declare their pub
 
 # Detailed design
 
-Components should not be able to directly access other components context anymore. To declare component's public interface use `provide` and pass any data that should be exposed. The object returned in `provide` would serve as a main access point for the accessor component. To eliminate conflicts and provide better cohesion use `Symbol` for exposed data property names.
+Components should not be able to directly access other components context anymore. To declare component's public interface authors must use a new `expose` options and describe the data that should be exposed.
+
+## `expose` option
+
+A several `expose` configurations should be supported.
 
-A component with such an interface could look like this:
+### Array of strings
 
 ```html
-<template>
-  <input ref="input">
-</template>
+<script>
+  export default {
+    expose: ['foo', 'bar', 'baz'],
+    data() {
+      return {
+        foo: null
+      }
+    },
+    methods: {
+      bar() {},
+    },
+    computed: {
+      baz() {}
+    }
+  }
+</script>
+```
+
+### Object syntax
 
+```html
 <script>
-  export const FOCUS_INPUT = Symbol()
-  
+  export const BAR_SYMBOL = Symbol()
+
   export default {
-    name: 'MyInput',
-    provide() {
-      const { focusInput } = this
+    expose: {
+      foo: 'bar', // expose 'foo' as 'bar'
+      bar: BAR_SYMBOL // expose 'bar' as a BAR_SYMBOL
+    },
+    data() {
+      return {
+        foo: null
+      }
+    },
+    methods: {
+      bar() {}
+    }
+  }
+</script>
+```
+
+### Function
+
+Functional configuration is more complicated because you can easily loose reactivity there.
+
+```html
+<script>
+  export default {
+    expose() {
+      const { foo, bar } = this
       return {
-        [FOCUS_INPUT]: focusInput
+        foo, // not reactive
+        bar
+      }
+    },
+    data() {
+      return {
+        foo: null
       }
     },
     methods: {
-      focusInput() {
-        this.$refs.input.focus()
+      bar() {},
+    }
+  }
+</script>
+```
+
+To solve this issue you could either go with the Composition API or wrap your data inside an object.
+
+```html
+<script>
+  export default {
+    expose() {
+      const { foo, bar } = this
+      return {
+        foo, // foo's value is reactive
+        bar
+      }
+    },
+    data() {
+      return {
+        foo: {
+          value: null
+        }
       }
+    },
+    methods: {
+      bar() {},
     }
   }
 </script>
 ```
 
-This interface could be utilized as following:
+**Composition API example**
+
+```html
+<script>
+  import { ref } from 'vue'
+
+  export default {
+    name: 'MyComponent',
+    setup() {
+      const foo = ref(null)
+      const bar = () => {}
+      return {
+        foo,
+        bar
+      }
+    },
+    expose() {
+      const { foo, bar } = this
+      return {
+        foo, // reactive
+        bar
+      }
+    },
+  }
+</script>
+```
+
+The exposed interface above could be utilized as following:
 
 ```html
 <template>
-  <MyInput :ref="myInput" />
+  <MyComponent :ref="myComponent" />
 </template>
 
 <script>
-  import { FOCUS_INPUT } from 'MyInput.vue'
-  
   export default {
     mounted() {
-      this.$refs.myInput[FOCUS_INPUT]()
+      console.log(this.$refs.myComponent.foo.value)
+      this.$refs.myComponent.bar()
     }
   }
 </script>
@@ -151,7 +245,7 @@ To expose refs use `mounted` hook and object as a wrapper to preserve reactivity
   export const INPUT_EXPOSED = Symbol()
   
   export default {
-    provide() {
+    expose() {
       const { exposed } = this
       return {
         [INPUT_EXPOSED]: exposed
@@ -182,7 +276,7 @@ Or function refs:
   export const INPUT_EXPOSED = Symbol()
   
   export default {
-    provide() {
+    expose() {
       const { exposed } = this
       return {
         [INPUT_EXPOSED]: exposed
@@ -211,7 +305,7 @@ Alternative way of accessing refs:
   
   export default {
     name: 'MyInput',
-    provide() {
+    expose() {
       return {
         [GET_INPUT_REF]: () => {
           return this.$refs.input
@@ -238,78 +332,15 @@ Alternative way of accessing refs:
 </script>
 ```
 
-Example using Composition API:
-
-```html
-<template>
-  <input ref="inputRef">
-</template>
-
-<script>
-  import { ref } from 'vue'
-  export const INPUT_REF = Symbol()
-  
-  export default {
-    name: 'MyInput',
-    setup() {
-      const inputRef = ref(null)
-      provide(INPUT_REF, inputRef)
-
-      return {
-        inputRef
-      }
-    }
-  }
-</script>
-```
-
-You'll then be able to use it as a ref:
-
-```html
-<template>
-  <MyInput ref="myInput" />
-</template>
-
-<script>
-  import { INPUT_REF } from 'MyInput.vue'
-  
-  export default {
-    setup() {
-      const myInput = ref(null)
-      onMounted(() => {
-        console.log(myInput.value[INPUT_REF].value)
-      })
-
-      return {
-        myInput
-      }
-    }
-  }
-</script>
-```
-
 # Drawbacks
 
-* Should be triggered after data init, `refs` then would require a lot of fiddling around to preserve reactivity (wrapping exposed values inside an object at a minimum)
-* Provides value down the render tree as a side-effect, which may not be the desired behaviour
-* This could cause performance penalty if any injections are used since we have to cycle through every provision in the vnode tree from bottom to top
+* `expose` should be executed after data init, `refs` then would require a lot of fiddling around to preserve reactivity (wrapping exposed values with an object at a minimum)
+* Could be difficult to implement
+* Not backwards compatible (but could only warn in compatibility build for example)
 
 # Alternatives
 
-* Use dedicated hook instead of `provide` but with exactly the same API. Could be called `expose`.
-
-  **Pros**:
-
-  * Does not cause conflicts with other provisions
-  * Clear separation of concerns
-
-  **Cons**:
-
-  * One more option to learn about
-  * Could be confusing to pick one between the `provide` and `expose`
-  * Does not fix the issue with `refs`
-
-* Use events to expose your component's public interface:  
+Using events to expose your component's public interface:  
   ```html
   <template>
     <input ref="input">
@@ -344,4 +375,33 @@ You'll then be able to use it as a ref:
 
 # Adoption strategy
 
-Components containing any data required by the parent component via `refs` would be required to explicitly declare their public interface.
\ No newline at end of file
+Components containing any data required by the parent component via `refs` would be required to explicitly declare their public interface.
+
+# Unresolved questions
+
+* Should it work with mixins?
+  
+  **Pros**:
+
+  * Clear contract between mixins and component
+
+  **Cons**:
+
+  * Would require a lot of changes if you use mixins extensively
+  * Rises entry barrier for mixin usage
+  * Does not solve other issues with mixins (implicit props, extending context)
+  * Could be complicated to implement (mixin can extend context but should only access exposed parts of it)
+  * Unclear whether mixins should be able to extend the `expose` property
+
+* Should it work with `$parent` access?
+
+* Should it work in tests?
+  
+  **Pros**:
+
+  * Explicit testing interface
+  * Tests for `expose` interface specifically
+
+  **Cons**:
+
+  * Could lead to exposing too much data just for testing which defeats the purpose
\ No newline at end of file

From 8a8ad02f2cb645b2b90c661e702172621c89a810 Mon Sep 17 00:00:00 2001
From: Stas Lashmanov <stasvarenkin@gmail.com>
Date: Fri, 28 Feb 2020 03:17:55 +0300
Subject: [PATCH 6/8] Add loose mode option

---
 active-rfcs/0000-component's-public-api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/active-rfcs/0000-component's-public-api.md b/active-rfcs/0000-component's-public-api.md
index 12395110..1366c1d1 100644
--- a/active-rfcs/0000-component's-public-api.md
+++ b/active-rfcs/0000-component's-public-api.md
@@ -376,6 +376,7 @@ Using events to expose your component's public interface:
 # Adoption strategy
 
 Components containing any data required by the parent component via `refs` would be required to explicitly declare their public interface.
+A `loose` mode configuration in `createApp` could be provided to opt-out of this behaviour.
 
 # Unresolved questions
 

From b5ac7d52e2ea92b82e0b04fb7fa9e3adbdbd70a3 Mon Sep 17 00:00:00 2001
From: Stas Lashmanov <stasvarenkin@gmail.com>
Date: Fri, 28 Feb 2020 18:40:09 +0300
Subject: [PATCH 7/8] Typo

---
 active-rfcs/0000-component's-public-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/active-rfcs/0000-component's-public-api.md b/active-rfcs/0000-component's-public-api.md
index 1366c1d1..1dbacfbc 100644
--- a/active-rfcs/0000-component's-public-api.md
+++ b/active-rfcs/0000-component's-public-api.md
@@ -70,7 +70,7 @@ After the change you'll be required to expose your data and methods explicitly.
     name: 'Parent',
     mounted() {
       this.$refs.input.focus() // exposed
-      this.$refs.input.blue() // error, not exposed
+      this.$refs.input.blur() // error, not exposed
     }
   }
 </script>

From 400fd1a01a5effcc13426c6a356115bba42354e6 Mon Sep 17 00:00:00 2001
From: Stas Lashmanov <stasvarenkin@gmail.com>
Date: Sat, 29 Feb 2020 18:59:15 +0300
Subject: [PATCH 8/8] Add suggested drawbacks

---
 active-rfcs/0000-component's-public-api.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/active-rfcs/0000-component's-public-api.md b/active-rfcs/0000-component's-public-api.md
index 1dbacfbc..63b1a9a7 100644
--- a/active-rfcs/0000-component's-public-api.md
+++ b/active-rfcs/0000-component's-public-api.md
@@ -337,6 +337,8 @@ Alternative way of accessing refs:
 * `expose` should be executed after data init, `refs` then would require a lot of fiddling around to preserve reactivity (wrapping exposed values with an object at a minimum)
 * Could be difficult to implement
 * Not backwards compatible (but could only warn in compatibility build for example)
+* Increased bundle size (could be disabled in production)
+* Decreased performance: a mechanism like a proxy is necessary to prevent specific properties to be accessible (could be disabled in production)
 
 # Alternatives