├── .github
    ├── ISSUE_TEMPLATE
    │   └── config.yml
    └── pull_request_template.md
├── .gitignore
├── .prettierrc
├── 0000-template.md
├── README.md
└── active-rfcs
    ├── 0001-new-slot-syntax.md
    ├── 0002-slot-syntax-shorthand.md
    ├── 0003-dynamic-directive-arguments.md
    ├── 0004-global-api-treeshaking.md
    ├── 0005-replace-v-bind-sync-with-v-model-argument.md
    ├── 0006-slots-unification.md
    ├── 0007-functional-async-api-change.md
    ├── 0008-render-function-api-change.md
    ├── 0009-global-api-change.md
    ├── 0011-v-model-api-change.md
    ├── 0012-custom-directive-api-change.md
    ├── 0013-composition-api.md
    ├── 0014-drop-keycode-support.md
    ├── 0015-remove-filters.md
    ├── 0016-remove-inline-templates.md
    ├── 0017-transition-as-root.md
    ├── 0018-transition-class-change.md
    ├── 0019-remove-data-object-declaration.md
    ├── 0020-events-api-change.md
    ├── 0021-router-link-scoped-slot.md
    ├── 0022-router-merge-meta-routelocation.md
    ├── 0023-scoped-styles-changes.md
    ├── 0024-attribute-coercion-behavior.md
    ├── 0025-teleport.md
    ├── 0026-async-component-api.md
    ├── 0027-custom-elements-interop.md
    ├── 0028-router-active-link.md
    ├── 0029-router-dynamic-routing.md
    ├── 0030-emits-option.md
    ├── 0031-attr-fallthrough.md
    ├── 0032-vtu-improve-async-workflow.md
    ├── 0033-router-navigation-failures.md
    ├── 0034-router-view-keep-alive-transitions.md
    ├── 0035-router-scroll-position.md
    ├── 0036-router-view-route-prop.md
    ├── 0037-router-return-guards.md
    ├── 0038-vue3-ie11-support.md
    ├── 0039-vtu-api.md
    ├── 0040-script-setup.md
    ├── 0041-reactivity-effect-scope.md
    ├── 0042-expose-api.md
    ├── 0043-sfc-style-variables.md
    └── 0044-router-push-history-state.md


/.github/ISSUE_TEMPLATE/config.yml:
--------------------------------------------------------------------------------
1 | blank_issues_enabled: false
2 | contact_links:
3 |   - name: 🙏 Question or Help
4 |     url: https://github.com/vuejs/rfcs/discussions/new
5 |     about: If you have a question or need help, ask a question on the discussion forums.
6 | 


--------------------------------------------------------------------------------
/.github/pull_request_template.md:
--------------------------------------------------------------------------------
 1 | ## Summary
 2 | 
 3 | <!--
 4 |   Short summary on what problem this RFC solves, and
 5 |   concise example usage of the feature
 6 | -->
 7 | 
 8 | ## Links
 9 | 
10 | <!--
11 |   Link to a GitHub-rendered version of your RFC, e.g.
12 |   https://github.com/<USERNAME>/rfcs/blob/<BRANCH>/active-rfcs/0000-my-proposal.md
13 |   You can find this link by navigating to this file on your branch.
14 | -->
15 | 
16 | - [Full Rendered Proposal]()
17 | 
18 | <!--
19 |   Please open and link to a corresponding discussion thread
20 |   (under "Discussion" tab of the repo).
21 |   After submitting the PR, make sure to edit the discussion
22 |   to link to this PR.
23 | -->
24 | 
25 | - [Discussion Thread]()
26 | 
27 | <!-- include additional links to related issues if applicable -->
28 | 
29 | ---
30 | 
31 | **Important: Do NOT comment on this PR. Please use the discussion thread linked above to provide feedback, as it provides branched discussions that are easier to follow. This also makes the edit history of the PR clearer.**
32 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | 


--------------------------------------------------------------------------------
/.prettierrc:
--------------------------------------------------------------------------------
1 | semi: false
2 | singleQuote: true
3 | printWidth: 80
4 | trailingComma: 'none'


--------------------------------------------------------------------------------
/0000-template.md:
--------------------------------------------------------------------------------
 1 | - Start Date: (fill me in with today's date, YYYY-MM-DD)
 2 | - Target Major Version: (2.x / 3.x)
 3 | - Reference Issues: (fill in existing related issues, if any)
 4 | - Implementation PR: (leave this empty)
 5 | 
 6 | # Summary
 7 | 
 8 | Brief explanation of the feature.
 9 | 
10 | # Basic example
11 | 
12 | If the proposal involves a new or changed API, include a basic code example.
13 | Omit this section if it's not applicable.
14 | 
15 | # Motivation
16 | 
17 | Why are we doing this? What use cases does it support? What is the expected
18 | outcome?
19 | 
20 | Please focus on explaining the motivation so that if this RFC is not accepted,
21 | the motivation could be used to develop alternative solutions. In other words,
22 | enumerate the constraints you are trying to solve without coupling them too
23 | closely to the solution you have in mind.
24 | 
25 | # Detailed design
26 | 
27 | This is the bulk of the RFC. Explain the design in enough detail for somebody
28 | familiar with Vue to understand, and for somebody familiar with the
29 | implementation to implement. This should get into specifics and corner-cases,
30 | and include examples of how the feature is used. Any new terminology should be
31 | defined here.
32 | 
33 | # Drawbacks
34 | 
35 | Why should we *not* do this? Please consider:
36 | 
37 | - implementation cost, both in term of code size and complexity
38 | - whether the proposed feature can be implemented in user space
39 | - the impact on teaching people Vue
40 | - integration of this feature with other existing and planned features
41 | - cost of migrating existing Vue applications (is it a breaking change?)
42 | 
43 | There are tradeoffs to choosing any path. Attempt to identify them here.
44 | 
45 | # Alternatives
46 | 
47 | What other designs have been considered? What is the impact of not doing this?
48 | 
49 | # Adoption strategy
50 | 
51 | If we implement this proposal, how will existing Vue developers adopt it? Is
52 | this a breaking change? Can we write a codemod? Can we provide a runtime adapter library for the original API it replaces? How will this affect other projects in the Vue ecosystem?
53 | 
54 | # Unresolved questions
55 | 
56 | Optional, but suggested for first drafts. What parts of the design are still
57 | TBD?
58 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Vue RFCs
  2 | 
  3 | ## What is an RFC?
  4 | 
  5 | The "RFC" (request for comments) process is intended to provide a
  6 | consistent and controlled path for new features to enter the framework.
  7 | 
  8 | Many changes, including bug fixes and documentation improvements can be
  9 | implemented and reviewed via the normal GitHub pull request workflow.
 10 | 
 11 | Some changes though are "substantial", and we ask that these be put
 12 | through a bit of a design process and produce a consensus among the Vue
 13 | [core team] and the community.
 14 | 
 15 | ## The RFC life-cycle
 16 | 
 17 | An RFC goes through the following stages:
 18 | 
 19 | - **Pending:** when the RFC is submitted as a discussion thread. We use discussions instead of Pull Requests as the former provides better discussion threading.
 20 | - **Active:** when an RFC is acknowledged and undergoing implementation. The feature may be shipped as experimental during this phase.
 21 | - **Landed:** when an RFC's proposed changes are shipped as stable in a release.
 22 | - **Rejected:** when an RFC is officially rejected or dropped.
 23 | 
 24 | ## When to follow this process
 25 | 
 26 | You need to follow this process if you intend to make "substantial"
 27 | changes to [Vue core](https://github.com/vuejs/core).
 28 | 
 29 | We are limiting the RFC process to core to keep the workflow manageable. If you wish to suggest changes to those other projects, please use their respective issue lists.
 30 | 
 31 | What constitutes a "substantial" change is evolving based on community norms, but may include the following:
 32 | 
 33 | - A new feature that creates new API surface area
 34 | - Changing the semantics or behavior of an existing API
 35 | - The removal of features that are already shipped as part of the release channel.
 36 | - The introduction of new idiomatic usage or conventions, even if they do not include code changes to Vue itself.
 37 | 
 38 | Some changes do not require an RFC:
 39 | 
 40 | - Additions that strictly improve objective, numerical quality criteria (speedup, better browser support)
 41 | - Fixing objectively incorrect behavior
 42 | - Rephrasing, reorganizing or refactoring
 43 | - Addition or removal of warnings
 44 | - Additions only likely to be _noticed by_ other implementors-of-Vue, invisible to users-of-Vue.
 45 | 
 46 | If you submit a pull request to implement a new feature without going
 47 | through the RFC process, it may be closed with a polite request to
 48 | submit an RFC first.
 49 | 
 50 | ## Why do you need to do this
 51 | 
 52 | It is great that you are considering suggesting new features or changes to Vue - we appreciate your willingness to contribute! However, as Vue becomes more widely used, we need to take stability more seriously, and thus have to carefully consider the impact of every change we make that may affect end users. On the other hand, we also feel that Vue has reached a stage where we want to start consciously preventing further complexity from new API surfaces.
 53 | 
 54 | These constraints and tradeoffs may not be immediately obvious to users who are proposing a change just to solve a specific problem they just ran into. The RFC process serves as a way to guide you through our thought process when making changes to Vue, so that we can be on the same page when discussing why or why not these changes should be made.
 55 | 
 56 | ## Gathering feedback before submitting
 57 | 
 58 | It's often helpful to get feedback on your concept before diving into the
 59 | level of API design detail required for an RFC. **You may open an
 60 | issue on this repo to start a high-level discussion**, with the goal of
 61 | eventually formulating an RFC pull request with the specific implementation
 62 | design.
 63 | 
 64 | ## What the process is
 65 | 
 66 | In short, to get a major feature added to Vue, one must first get the
 67 | RFC merged into the RFC repo as a markdown file. At that point the RFC
 68 | is 'active' and may be implemented with the goal of eventual inclusion
 69 | into Vue.
 70 | 
 71 | 1.  Work on your proposal in a Markdown file based on the template (`0000-template.md`) found in this repo.
 72 | 
 73 |     - Put care into the details: **RFCs that do not present convincing motivation, demonstrate understanding of the impact of the design, or are disingenuous about the drawbacks or alternatives tend to be poorly-received**.
 74 | 
 75 | 2.  Open a new thread in [Discussions](https://github.com/vuejs/rfcs/discussions) and make sure to set category to "RFC Discussions".
 76 | 
 77 |     - Build consensus and integrate feedback in the discussion thread. RFCs that have broad support are much more likely to make progress than those that don't receive any comments.
 78 | 
 79 | 3.  Eventually, the [core team] will decide whether the RFC is a candidate
 80 |     for inclusion in Vue.
 81 | 
 82 |     - An RFC can be modified based upon feedback from the [core team] and community. Significant modifications may trigger a new final comment period.
 83 | 
 84 |     - An RFC may be rejected after public discussion has settled and comments have been made summarizing the rationale for rejection. A member of the [core team] should then close the RFC's associated pull request.
 85 | 
 86 |     - An RFC may be accepted at the close of its final comment period. A [core team] member will merge the RFC's associated pull request, at which point the RFC will become 'active'.
 87 | 
 88 | 4.  If the proposal has been approved for inclusion, you can prepare a Pull Request:
 89 | 
 90 |     - Fork this repo.
 91 | 
 92 |     - Create your proposal as `active-rfcs/0000-my-feature.md` (where "my-feature" is descriptive. don't assign an RFC number yet).
 93 | 
 94 |     - Submit a pull request. Make sure to link to the discussion thread.
 95 | 
 96 | ## Details on Active RFCs
 97 | 
 98 | Once an RFC becomes active then authors may implement it and submit the
 99 | feature as a pull request to the Vue core repo. Becoming 'active' is not a rubber stamp, and in particular still does not mean the feature will ultimately
100 | be merged; it does mean that the [core team] has agreed to it in principle
101 | and are amenable to merging it.
102 | 
103 | Furthermore, the fact that a given RFC has been accepted and is
104 | 'active' implies nothing about what priority is assigned to its
105 | implementation, nor whether anybody is currently working on it.
106 | 
107 | Modifications to active RFC's can be done in followup PR's. We strive
108 | to write each RFC in a manner that it will reflect the final design of
109 | the feature; but the nature of the process means that we cannot expect
110 | every merged RFC to actually reflect what the end result will be at
111 | the time of the next major release; therefore we try to keep each RFC
112 | document somewhat in sync with the language feature as planned,
113 | tracking such changes via followup pull requests to the document.
114 | 
115 | ## Implementing an RFC
116 | 
117 | The author of an RFC is not obligated to implement it. Of course, the
118 | RFC author (like any other developer) is welcome to post an
119 | implementation for review after the RFC has been accepted.
120 | 
121 | An active RFC should have the link to the implementation PR listed if there is one. Feedback to the actual implementation should be conducted in the implementation PR instead of the original RFC PR.
122 | 
123 | If you are interested in working on the implementation for an 'active'
124 | RFC, but cannot determine if someone else is already working on it,
125 | feel free to ask (e.g. by leaving a comment on the associated issue).
126 | 
127 | ## Reviewing RFC's
128 | 
129 | Members of the [core team] will attempt to review some set of open RFC
130 | pull requests on a regular basis. If a [core team] member believes an RFC PR is ready to be accepted into active status, they can approve the PR using GitHub's review feature to signal their approval of the RFC.
131 | 
132 | **Vue's RFC process owes its inspiration to the [React RFC process], [Rust RFC process] and [Ember RFC process]**
133 | 
134 | [react rfc process]: https://github.com/reactjs/rfcs
135 | [rust rfc process]: https://github.com/rust-lang/rfcs
136 | [ember rfc process]: https://github.com/emberjs/rfcs
137 | [core team]: https://vuejs.org/about/team.html
138 | 


--------------------------------------------------------------------------------
/active-rfcs/0001-new-slot-syntax.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-01-14
  2 | - Target Major Version: 2.x & 3.x
  3 | - Reference Issues: https://github.com/vuejs/vue/issues/7740, https://github.com/vuejs/vue/issues/9180, https://github.com/vuejs/vue/issues/9306
  4 | - Implementation PR: (leave this empty)
  5 | 
  6 | # Summary
  7 | 
  8 | Introducing a new syntax for scoped slots usage:
  9 | 
 10 | - New directive `v-slot` that unifies `slot` and `slot-scope` in a single directive syntax.
 11 | 
 12 | - Shorthand for `v-slot` that can potentially unify the usage of both scoped and normal slots.
 13 | 
 14 | # Basic example
 15 | 
 16 | Using `v-slot` to declare the props passed to the scoped slots of `<foo>`:
 17 | 
 18 | ``` html
 19 | <!-- default slot -->
 20 | <foo v-slot="{ msg }">
 21 |   {{ msg }}
 22 | </foo>
 23 | 
 24 | <!-- named slot -->
 25 | <foo>
 26 |   <template v-slot:one="{ msg }">
 27 |     {{ msg }}
 28 |   </template>
 29 | </foo>
 30 | ```
 31 | 
 32 | # Motivation
 33 | 
 34 | When we first introduced scoped slots, it was verbose because it required always using `<template slot-scope>`:
 35 | 
 36 | ``` html
 37 | <foo>
 38 |   <template slot-scope="{ msg }">
 39 |     <div>{{ msg }}</div>
 40 |   </template>
 41 | </foo>
 42 | ```
 43 | 
 44 | To make it less verbose, in 2.5 we introduced the ability to use `slot-scope` directly on the slot element:
 45 | 
 46 | ``` html
 47 | <foo>
 48 |   <div slot-scope="{ msg }">
 49 |     {{ msg }}
 50 |   </div>
 51 | </foo>
 52 | ```
 53 | 
 54 | This means it works on component as slot as well:
 55 | 
 56 | ``` html
 57 | <foo>
 58 |   <bar slot-scope="{ msg }">
 59 |     {{ msg }}
 60 |   </bar>
 61 | </foo>
 62 | ```
 63 | 
 64 | However, the above usage leads to a problem: the placement of `slot-scope` doesn't always clearly reflect which component is actually providing the scope variable. Here `slot-scope` is placed on the `<bar>` component, but it's actually defining a scope variable provided by the default slot of `<foo>`.
 65 | 
 66 | This gets worse as the nesting deepens:
 67 | 
 68 | ``` html
 69 | <foo>
 70 |   <bar slot-scope="foo">
 71 |     <baz slot-scope="bar">
 72 |       <div slot-scope="baz">
 73 |         {{ foo }} {{ bar }} {{ baz }}
 74 |       </div>
 75 |     </baz>
 76 |   </bar>
 77 | </foo>
 78 | ```
 79 | 
 80 | It's not immediately clear which component is providing which variable in this template.
 81 | 
 82 | Someone suggested that we should allow using `slot-scope` on a component itself to denote its default slot's scope:
 83 | 
 84 | ``` html
 85 | <foo slot-scope="foo">
 86 |   {{ foo }}
 87 | </foo>
 88 | ```
 89 | 
 90 | Unfortunately, this cannot work as it would lead to ambiguity with component nesting:
 91 | 
 92 | ``` html
 93 | <parent>
 94 |   <foo slot-scope="foo"> <!-- provided by parent or by foo? -->
 95 |     {{ foo }}
 96 |   </foo>
 97 | </parent>
 98 | ```
 99 | 
100 | This is why I now believe allowing using `slot-scope` without a template was a mistake.
101 | 
102 | ### Why a new directive instead of fixing `slot-scope`?
103 | 
104 | If we can go back in time, I would probably change the semantics of `slot-scope` - but:
105 | 
106 | 1. That would be a breaking change now, and that means we will never be able to ship it in 2.x.
107 | 
108 | 2. Even if we change it in 3.x, changing the semantics of existing syntax can cause a LOT of confusion for future learners that Google into outdated learning materials. We definitely want to avoid that. So, we have to introduce something new to differentiate from `slot-scope`.
109 | 
110 | 3. In 3.x, we plan to unify slot types so it's no longer necessary to differentiate between scoped vs. non-scoped slots (conceptually). A slot may or may not receive props, but they are all just slots. With this conceptual unification, having `slot` and `slot-scope` being two special attributes seems unnecessary, and it would be nice to unify the syntax under a single construct as well.
111 | 
112 | # Detailed design
113 | 
114 | ### Introducing a new directive: `v-slot`.
115 | 
116 | - It can be used on `<template>` slot containers to denote slots passed to a component, where the slot name is expressed via the **directive argument**:
117 | 
118 |   ``` html
119 |   <foo>
120 |     <template v-slot:header>
121 |       <div class="header"></div>
122 |     </template>
123 | 
124 |     <template v-slot:body>
125 |       <div class="body"></div>
126 |     </template>
127 | 
128 |     <template v-slot:footer>
129 |       <div class="footer"></div>
130 |     </template>
131 |   </foo>
132 |   ```
133 | 
134 |   If any slot is a scoped slot which receives props, the received slot props can be declared using the directive's attribute value. The value of `v-slot` works the same way as `slot-scope`, so JavaScript argument destructuring is supported:
135 | 
136 |   ``` html
137 |   <foo>
138 |     <template v-slot:header="{ msg }">
139 |       <div class="header">
140 |         Message from header slot: {{ msg }}
141 |       </div>
142 |     </template>
143 |   </foo>
144 |   ```
145 | 
146 | - `v-slot` can be used directly on a component, without an argument, to indicate that the component's default slot is a scoped slot, and that props passed to the default slot should be available as the variable declared in its attribute value:
147 | 
148 |   ``` html
149 |   <foo v-slot="{ msg }">
150 |     {{ msg }}
151 |   </foo>
152 |   ```
153 | 
154 | ### Comparison: New vs. Old
155 | 
156 | Let's review whether this proposal achieves our goals outlined above:
157 | 
158 | - Still provide succinct syntax for most common use cases of scoped slots (single default slot):
159 | 
160 |   ``` html
161 |   <foo v-slot="{ msg }">{{ msg }}</foo>
162 |   ```
163 | 
164 | - Clearer connection between scoped variable and the component that is providing it:
165 | 
166 |   Let's take another look at the deep-nesting example using current syntax (`slot-scope`) - notice how slot scope variables provided by `<foo>` is declared on `<bar>`, and the variable provided by `<bar>` is declared on `<baz>`...
167 | 
168 |   ``` html
169 |   <foo>
170 |     <bar slot-scope="foo">
171 |       <baz slot-scope="bar">
172 |         <div slot-scope="baz">
173 |           {{ foo }} {{ bar }} {{ baz }}
174 |         </div>
175 |       </baz>
176 |     </bar>
177 |   </foo>
178 |   ```
179 | 
180 |   This is the equivalent using the new syntax:
181 | 
182 |   ``` html
183 |   <foo v-slot="foo">
184 |     <bar v-slot="bar">
185 |       <baz v-slot="baz">
186 |         {{ foo }} {{ bar }} {{ baz }}
187 |       </baz>
188 |     </bar>
189 |   </foo>
190 |   ```
191 | 
192 |   Notice that **the scope variable provided by a component is also declared on that component itself**. The new syntax shows a clearer connection between slot variable declaration and the component providing the variable.
193 | 
194 | ### More Usage Comparisons
195 | 
196 | #### Default slot with text
197 | 
198 | ``` html
199 | <!-- old -->
200 | <foo>
201 |   <template slot-scope="{ msg }">
202 |     {{ msg }}
203 |   </template>
204 | </foo>
205 | 
206 | <!-- new -->
207 | <foo v-slot="{ msg }">
208 |   {{ msg }}
209 | </foo>
210 | ```
211 | 
212 | #### Default slot with element
213 | 
214 | ``` html
215 | <!-- old -->
216 | <foo>
217 |   <div slot-scope="{ msg }">
218 |     {{ msg }}
219 |   </div>
220 | </foo>
221 | 
222 | <!-- new -->
223 | <foo v-slot="{ msg }">
224 |   <div>
225 |     {{ msg }}
226 |   </div>
227 | </foo>
228 | ```
229 | 
230 | #### Nested default slots
231 | 
232 | ``` html
233 | <!-- old -->
234 | <foo>
235 |   <bar slot-scope="foo">
236 |     <baz slot-scope="bar">
237 |       <template slot-scope="baz">
238 |         {{ foo }} {{ bar }} {{ baz }}
239 |       </template>
240 |     </baz>
241 |   </bar>
242 | </foo>
243 | 
244 | <!-- new -->
245 | <foo v-slot="foo">
246 |   <bar v-slot="bar">
247 |     <baz v-slot="baz">
248 |       {{ foo }} {{ bar }} {{ baz }}
249 |     </baz>
250 |   </bar>
251 | </foo>
252 | ```
253 | 
254 | #### Named slots
255 | 
256 | ``` html
257 | <!-- old -->
258 | <foo>
259 |   <template slot="one" slot-scope="{ msg }">
260 |     text slot: {{ msg }}
261 |   </template>
262 | 
263 |   <div slot="two" slot-scope="{ msg }">
264 |     element slot: {{ msg }}
265 |   </div>
266 | </foo>
267 | 
268 | <!-- new -->
269 | <foo>
270 |   <template v-slot:one="{ msg }">
271 |     text slot: {{ msg }}
272 |   </template>
273 | 
274 |   <template v-slot:two="{ msg }">
275 |     <div>
276 |       element slot: {{ msg }}
277 |     </div>
278 |   </template>
279 | </foo>
280 | ```
281 | 
282 | #### Nested & mixed usage of named / default slots
283 | 
284 | ``` html
285 | <!-- old -->
286 | <foo>
287 |   <bar slot="one" slot-scope="one">
288 |     <div slot-scope="bar">
289 |       {{ one }} {{ bar }}
290 |     </div>
291 |   </bar>
292 | 
293 |   <bar slot="two" slot-scope="two">
294 |     <div slot-scope="bar">
295 |       {{ two }} {{ bar }}
296 |     </div>
297 |   </bar>
298 | </foo>
299 | 
300 | <!-- new -->
301 | <foo>
302 |   <template v-slot:one="one">
303 |     <bar v-slot="bar">
304 |       <div>{{ one }} {{ bar }}</div>
305 |     </bar>
306 |   </template>
307 | 
308 |   <template v-slot:two="two">
309 |     <bar v-slot="bar">
310 |       <div>{{ two }} {{ bar }}</div>
311 |     </bar>
312 |   </template>
313 | </foo>
314 | ```
315 | 
316 | # Drawbacks
317 | 
318 | - Introducing a new syntax introduces churn and makes a lot of learning materials covering this topic in the ecosystem outdated. New users may get confused by discovering a new syntax after going through existing tutorials.
319 | 
320 |   - We need good documentation updates on scoped slots to help with this.
321 | 
322 | - The default slot usage `v-slot="{ msg }"` doesn't precisely convey the concept that `msg` is being passed to the slot as a prop.
323 | 
324 | # Alternatives
325 | 
326 | - New special attribute `slot-props` ([as a previous version of this draft](https://github.com/vuejs/rfcs/blob/8575e72d5a401db5d7206e127e3a6012491d68ed/active-rfcs/0000-new-scoped-slots-syntax.md))
327 | - Directive (`v-scope`) instead of a special attribute as originally proposed in [#9180](https://github.com/vuejs/vue/issues/9180);
328 | - Alternative shorthand symbol (`&`) as suggested by @rellect [here](https://github.com/vuejs/vue/issues/9306#issuecomment-453946190)
329 | 
330 | # Adoption strategy
331 | 
332 | The change is fully backwards compatible, so we can roll it out in a minor release (planned for 2.6).
333 | 
334 | `slot-scope` is going to be soft-deprecated: it will be marked deprecated in the docs, and we would encourage everyone to use / switch to the new syntax, but we won't bug you with deprecation messages just yet because we know it's not a top priority for everyone to always migrate to the newest stuff.
335 | 
336 | In 3.0 we do plan to eventually remove `slot-scope`, and only support the new syntax. We will start emitting deprecation messages for `slot-scope` usage in the next 2.x minor release to ease the migration to 3.0.
337 | 
338 | Since this is a pretty well defined syntax change, we can potentially provide a migration tool that can automatically convert your templates to the new syntax.
339 | 


--------------------------------------------------------------------------------
/active-rfcs/0002-slot-syntax-shorthand.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-01-16
  2 | - Target Major Version: (2.x / 3.x)
  3 | - Reference Issues: https://github.com/vuejs/rfcs/pull/2
  4 | - Implementation PR: (leave this empty)
  5 | 
  6 | # Summary
  7 | 
  8 | Add shorthand syntax for the `v-slot` syntax proposed in [rfc-0001](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0001-new-slot-syntax.md). Please make sure to read it first to get proper context for this proposal.
  9 | 
 10 | # Basic example
 11 | 
 12 | ``` html
 13 | <foo>
 14 |   <template #header="{ msg }">
 15 |     Message from header: {{ msg }}
 16 |   </template>
 17 | 
 18 |    <template #footer>
 19 |     A static footer
 20 |   </template>
 21 | </foo>
 22 | ```
 23 | 
 24 | # Motivation
 25 | 
 26 | A shorthand, as the name entails, primarily aims to provide more succinct syntax.
 27 | 
 28 | In Vue we currently provide shorthands only for two directives: `v-bind` and `v-on`:
 29 | 
 30 | ``` html
 31 | <div v-bind:id="id"></div>
 32 | <div :id="id"></div>
 33 | 
 34 | <button v-on:click="onClick"></button>
 35 | <button @click="onClick"></button>
 36 | ```
 37 | 
 38 | `v-bind` and `v-on` often get used repeatedly on the same element, and can get verbose when the information differing between each is **the directive argument** instead of the directive itself. **Shorthands thus help improve the signal/noise ratio by shortening the parts that are duplicated (`v-xxx`) and highlighting the parts that are different (the arguments).**
 39 | 
 40 | The new `v-slot` syntax can also get the same problem in components that expect multiple slots:
 41 | 
 42 | ``` html
 43 | <TestComponent>
 44 |   <template v-slot:one="{ name }">Hello {{ name }}</template>
 45 |   <template v-slot:two="{ name }">Hello {{ name }}</template>
 46 |   <template v-slot:three="{ name }">Hello {{name }}</template>
 47 | </TestComponent>
 48 | ```
 49 | 
 50 | Here `v-slot` is repeated multiple times where the actual differing part is the slot name (denoted by the argument).
 51 | 
 52 | The shorthand helps slot names to be more easily scan-able:
 53 | 
 54 | ``` html
 55 | <TestComponent>
 56 |   <template #one="{ name }">Hello {{ name }}</template>
 57 |   <template #two="{ name }">Hello {{ name }}</template>
 58 |   <template #three="{ name }">Hello {{name }}</template>
 59 | </TestComponent>
 60 | ```
 61 | 
 62 | # Detailed design
 63 | 
 64 | The shorthand follows very similar rules to the shorthand of `v-bind` and `v-on`: replace the directive name plus the colon with the shorthand symbol (`#`).
 65 | 
 66 | ``` html
 67 | <!-- full syntax -->
 68 | <foo>
 69 |   <template v-slot:header="{ msg }">
 70 |     Message from header: {{ msg }}
 71 |   </template>
 72 | 
 73 |    <template v-slot:footer>
 74 |     A static footer
 75 |   </template>
 76 | </foo>
 77 | 
 78 | <!-- shorthand -->
 79 | <foo>
 80 |   <template #header="{ msg }">
 81 |     Message from header: {{ msg }}
 82 |   </template>
 83 | 
 84 |    <template #footer>
 85 |     A static footer
 86 |   </template>
 87 | </foo>
 88 | ```
 89 | 
 90 | **Similar to `v-bind` and `v-on`, the shorthand only works when an argument is present. This means `v-slot` without an argument cannot be simplified to `#=`.** For default slots, either the full syntax (`v-slot`) or an explicit name (`#default`) should be used.
 91 | 
 92 | ``` html
 93 | <foo v-slot="{ msg }">
 94 |   {{ msg }}
 95 | </foo>
 96 | 
 97 | <foo #default="{ msg }">
 98 |   {{ msg }}
 99 | </foo>
100 | ```
101 | 
102 | The choice of `#` is a selection based on the feedback collected in the previous RFC. It holds a resemblance to the id selector in CSS and translates quite well conceptually to stand for a slot's name.
103 | 
104 | Some example usage in a real-world library that relies on scoped slots ([vue-promised](https://github.com/posva/vue-promised)):
105 | 
106 |  ``` html
107 | <Promised :promise="usersPromise">
108 |   <template #pending>
109 |     <p>Loading...</p>
110 |   </template>
111 | 
112 |    <template #default="users">
113 |     <ul>
114 |       <li v-for="user in users">{{ user.name }}</li>
115 |     </ul>
116 |   </template>
117 | 
118 |    <template #rejected="error">
119 |     <p>Error: {{ error.message }}</p>
120 |   </template>
121 | </Promised>
122 | ```
123 | 
124 | # Drawbacks
125 | 
126 | - Some may argue that slots are not that commonly used and therefore don't really need a shorthand, and it could result in extra learning curve for beginners. In response to that:
127 | 
128 |   1. I believe scoped slot is an important mechanism for building 3rd party component suites that are highly customizable and composable. I think we will see more component libraries relying on slots for customization and composition in the future. For a user using such a component library, a shorthand will become quite valuable (as demonstrated in the examples).
129 | 
130 |   2. The translation rules for the shorthand is straightforward and consistent with existing shorthands. If the user learns how the base syntax works, understanding the shorthand is a minimal extra step.
131 | 
132 | # Alternatives
133 | 
134 | Some alternative symbols have been presented and discussed in the previous RFC. The only other one with similarly positive interest is `&`:
135 | 
136 | ``` html
137 | <foo>
138 |   <template &header="{ msg }">
139 |     Message from header: {{ msg }}
140 |   </template>
141 | 
142 |    <template &footer>
143 |     A static footer
144 |   </template>
145 | </foo>
146 | ```
147 | 
148 | # Adoption strategy
149 | 
150 | This should be a natural extension on top of the new `v-slot` syntax. Ideally, we'd want introduce the base syntax and the shorthand at the same time so users learn both at the same time. Introducing the shorthand at a later time runs the risk of some users only aware of the `v-slot` syntax and get confused when seeing the shorthand in others' code.
151 | 
152 | # Unresolved questions
153 | 
154 | N/A
155 | 


--------------------------------------------------------------------------------
/active-rfcs/0003-dynamic-directive-arguments.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-01-16
  2 | - Target Major Version: (2.x / 3.x)
  3 | - Reference Issues: https://github.com/vuejs/rfcs/pull/2, https://github.com/vuejs/rfcs/pull/3
  4 | - Implementation PR: https://github.com/vuejs/vue/pull/9373
  5 | # Summary
  6 | 
  7 | Support dynamic values in directive arguments.
  8 | 
  9 | # Basic example
 10 | 
 11 | ``` html
 12 | <div v-bind:[key]="value"></div>
 13 | <div v-on:[event]="handler"></div>
 14 | ```
 15 | 
 16 | # Motivation
 17 | 
 18 | Due to directive arguments being static, currently users would have to resort to argument-less object bindings in order to leverage dynamic keys:
 19 | 
 20 | ``` html
 21 | <div v-bind="{ [key]: value }"></div>
 22 | <div v-on="{ [event]: handler }"></div>
 23 | ```
 24 | 
 25 | However, this has a few issues:
 26 | 
 27 | - It's a lesser known technique that relies on knowledge of the object-based syntax for `v-bind`/`v-on` and the existence of computed property keys in JavaScript.
 28 | 
 29 | - It generates less efficient code: an ad-hoc object is allocated and if there are other static bindings on the same element, it has to be dynamically iterated and mixed into the existing data object. The code looks roughly like this:
 30 | 
 31 |   ``` js
 32 |   return h('div', {
 33 |     on: Object.assign({
 34 |       click: onClick
 35 |     }, {
 36 |       [event]: handler
 37 |     })
 38 |   })
 39 |   ```
 40 | 
 41 |   Where as with dynamic arguments we can directly generate:
 42 | 
 43 |   ``` js
 44 |   return h('div', {
 45 |     on: {
 46 |       click: onClick,
 47 |       [event]: handler
 48 |     }
 49 |   })
 50 |   ```
 51 | 
 52 | In addition, `v-slot` doesn't have an equivalent object syntax, since it's value is used for declaring the slot scope variable. So without the dynamic argument, the `v-slot` syntax will not be able to support dynamic slot names. Although this is probably a very rare use case, it would be a pain having to rewrite an entire template into render function just because of this single limitation.
 53 | 
 54 | # Detailed design
 55 | 
 56 | ``` html
 57 | <!-- v-bind with dynamic key -->
 58 | <div v-bind:[key]="value"></div>
 59 | 
 60 | <!-- v-bind shorthand with dynamic key -->
 61 | <div :[key]="value"></div>
 62 | 
 63 | <!-- v-on with dynamic event -->
 64 | <div v-on:[event]="handler"></div>
 65 | 
 66 | <!-- v-on shorthand with dynamic event -->
 67 | <div @[event]="handler"></div>
 68 | 
 69 | <!-- v-slot with dynamic name -->
 70 | <foo>
 71 |   <template v-slot:[name]>
 72 |     Hello
 73 |   </template>
 74 | </foo>
 75 | 
 76 | <!-- v-slot shorthand with dynamic name -->
 77 | <!-- pending #3 -->
 78 | <foo>
 79 |   <template #[name]>
 80 |     Default slot
 81 |   </template>
 82 | </foo>
 83 | ```
 84 | 
 85 | ### Handling of `null` as Special Value
 86 | 
 87 | Dynamic argument values are expected to be strings. However, it would be convenient if we allow `null` as a special value that explicitly indicates that the binding should be removed. Any other non-string values are likely mistakes and will trigger a warning.
 88 | 
 89 | `null` as a special value only applies to `v-bind` and `v-on`, but not `v-slot`. This is because `v-slot` is not a binding and cannot be removed. Custom directives have the liberty of deciding how to handle non-string arguments, but are expected to follow the convention when it applies.
 90 | 
 91 | # Drawbacks / Considerations
 92 | 
 93 | ### Constraints on expressions
 94 | 
 95 | Theoretically this opens up the directive argument to arbitrarily complex JavaScript expressions, but html attribute names cannot contain spaces and quotes, so in some cases the user may get tripped up with something like:
 96 | 
 97 | ``` html
 98 | <div :[key + 'foo']="value"></div>
 99 | ```
100 | 
101 | Which does not work as expected. A workaround would be:
102 | 
103 | ``` html
104 | <div :[`${key}foo`]="value"></div>
105 | ```
106 | 
107 | That said, complex dynamic key bindings should probably be pre-transformed in JavaScript via a computed property.
108 | 
109 | **Update:**: it is possible to detect such usage and provide proper warnings in the parser (by checking for arguments that are missing the closing bracket).
110 | 
111 | ### Custom Directives
112 | 
113 | Allowing dynamic arguments for all directives means custom directive implementations now also need to account for potential argument changes in addition to value changes.
114 | 
115 | This also requires the addition of `binding.oldArgs` to the custom directive binding context.
116 | 
117 | # Alternatives
118 | 
119 | N/A
120 | 
121 | # Adoption strategy
122 | 
123 | This is non-breaking and should be straightforward to introduce with appropriate documentation updates.
124 | 
125 | # Unresolved questions
126 | 
127 | N/A
128 | 


--------------------------------------------------------------------------------
/active-rfcs/0004-global-api-treeshaking.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-03-01
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: N/A
  4 | - Implementation PR: N/A
  5 | 
  6 | # Summary
  7 | 
  8 | Make Vue runtime tree-shakable by exposing as much APIs through named exports as possible.
  9 | 
 10 | # Basic example
 11 | 
 12 | ```js
 13 | import { nextTick, observable } from 'vue'
 14 | 
 15 | nextTick(() => {})
 16 | 
 17 | const obj = observable({})
 18 | ```
 19 | 
 20 | # Motivation
 21 | 
 22 | As Vue's API grows, we are constantly trying to balance the tradeoff between features and bundle sizes. We want to keep Vue's size overhead to a minimum, but we also don't want to limit its capability because of the size constraint.
 23 | 
 24 | With ES modules' static analysis friendly design, modern bundlers combined with minifiers can now eliminate ES modules exports that are not used anywhere in the bundle. We can restructure Vue's global and internal APIs to take advantage of this so that users only pay for the features they actually use.
 25 | 
 26 | In addition, knowing that optional features won't increase the bundle size for users not using them, we now have more room to include optional features in the core.
 27 | 
 28 | # Detailed design
 29 | 
 30 | Currently in 2.x, all global APIs are exposed on the single Vue object:
 31 | 
 32 | ```js
 33 | import Vue from 'vue'
 34 | 
 35 | Vue.nextTick(() => {})
 36 | 
 37 | const obj = Vue.observable({})
 38 | ```
 39 | 
 40 | In 3.x, they can **only** be accessed as named imports:
 41 | 
 42 | ```js
 43 | import Vue, { nextTick, observable } from 'vue'
 44 | 
 45 | Vue.nextTick // undefined
 46 | 
 47 | nextTick(() => {})
 48 | 
 49 | const obj = observable({})
 50 | ```
 51 | 
 52 | By not attaching all APIs on the `Vue` default export, any unused APIs can be dropped in the final bundle produced by a bundler that supports tree-shaking.
 53 | 
 54 | ## Affected 2.x APIs
 55 | 
 56 | - `Vue.nextTick`
 57 | - `Vue.observable`
 58 | - `Vue.version`
 59 | - `Vue.compile` (only in full builds)
 60 | - `Vue.set` (only in compat builds)
 61 | - `Vue.delete` (only in compat builds)
 62 | 
 63 | ## Internal Helpers
 64 | 
 65 | In addition to public APIs, many of the internal components / helpers can be exported as named exports as well. This allows the compiler to output code that only imports features when they are used. For example the following template:
 66 | 
 67 | ```html
 68 | <transition>
 69 |   <div v-show="ok">hello</div>
 70 | </transition>
 71 | ```
 72 | 
 73 | Can be compiled into the following (for explanation purposes, not exact output):
 74 | 
 75 | ``` js
 76 | import { h, Transition, applyDirectives, vShow } from 'vue'
 77 | 
 78 | export function render() {
 79 |   return h(Transition, [
 80 |     applyDirectives(h('div', 'hello'), this, [vShow, this.ok])
 81 |   ])
 82 | }
 83 | ```
 84 | 
 85 | This means the `Transition` component only gets imported when the application actually makes use of it.
 86 | 
 87 | **Note the above only applies to the ES Modules builds for use with tree-shaking capable bundlers - the UMD build still includes all features and exposes everything on the `Vue` global variable (and the compiler will produce appropriate output to use APIs off the global instead of importing).**
 88 | 
 89 | # Drawbacks
 90 | 
 91 | Users can no longer import a single `Vue` variable and then use APIs off of it. However this should be a worthwhile tradeoff for minimal bundle sizes.
 92 | 
 93 | ## Global API usage in plugins
 94 | 
 95 | Some plugins may rely on global APIs originally exposed on `Vue`:
 96 | 
 97 | ```js
 98 | const plugin = {
 99 |   install: Vue => {
100 |     Vue.nextTick(() => {
101 |       // ...
102 |     })
103 |   }
104 | }
105 | ```
106 | 
107 | In 3.0 they will need to import these explicitly:
108 | 
109 | ```js
110 | import { nextTick } from 'vue'
111 | 
112 | const plugin = {
113 |   install: app => {
114 |     nextTick(() => {
115 |       // ...
116 |     })
117 |   }
118 | }
119 | ```
120 | 
121 | This creates a bit of overhead since it requires library authors to properly configure the externalization of Vue in their build setup:
122 | 
123 | - Vue should not be bundled into the library;
124 | - For module builds, the import should be left alone and be handled by the end user bundler;
125 | - For UMD / browser builds, it should try the global `Vue.h` first and fallback to `require` calls.
126 | 
127 | This is common practice for React libs and possible with both webpack and Rollup. A decent number of Vue libs also already does this. We just need to provide proper documentation and tooling support.
128 | 
129 | # Alternatives
130 | 
131 | N/A
132 | 
133 | # Adoption strategy
134 | 
135 | It should be possible to provide a code mod for this as part of the migration tool.
136 | 


--------------------------------------------------------------------------------
/active-rfcs/0005-replace-v-bind-sync-with-v-model-argument.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-01-28
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: https://github.com/vuejs/vue-next/issues/8
  4 | - Implementation PR: (leave this empty)
  5 | 
  6 | ## Summary
  7 | 
  8 | Removing `v-bind`'s `.sync` modifier and replacing it with an argument on `v-model`.
  9 | 
 10 | ## Basic example
 11 | 
 12 | Instead of:
 13 | 
 14 | ```vue
 15 | <MyComponent v-bind:title.sync="title" />
 16 | ```
 17 | 
 18 | the syntax would be:
 19 | 
 20 | ```vue
 21 | <MyComponent v-model:title="title" />
 22 | ```
 23 | 
 24 | ## Motivation
 25 | 
 26 | I've seen `v-bind.sync` cause quite a bit of confusion in Vue 2, as users expect to be able to use expressions like with v-bind (despite whatever we put in the docs). The explanation I've had the best success with is:
 27 | 
 28 | > Thinking about `v-bind:title.sync="title"` like a normal binding with extra behavior is really the wrong way to think about it, because two-way bindings are fundamentally different. The `.sync` modifier works essentially like v-model, which is Vue's other syntax sugar for creating a two-way binding. The main difference is that it expands to a slightly different pattern that allows you to have multiple two-way bindings on a single component, rather than being limited to just one.
 29 | 
 30 | Which brings me to the question: if it helps to tell users _not_ to think of `v-bind.sync` like `v-bind`, but rather to think about it like `v-model`, should it be part of the `v-model` API instead?
 31 | 
 32 | ## Detailed design
 33 | 
 34 | > **NOTE**: Though not part of this proposal, `v-model`'s implementation details are likely to change in Vue 3 to make common patterns like transparent wrapper components easier to implement. When you see the `modelValue` attribute and `update:modelValue` event, know they are a placeholder for however we implement `v-model`'s special behavior with form elements and _not_ a recommendation included in this proposal.
 35 | 
 36 | ### On an element
 37 | 
 38 | ```vue
 39 | <input v-model="xxx">
 40 | 
 41 | <!-- would be shorthand for: -->
 42 | 
 43 | <input
 44 |   :model-value="xxx"
 45 |   @update:model-value="newValue => { xxx = newValue }"
 46 | >
 47 | ```
 48 | 
 49 | ```vue
 50 | <input v-model:aaa="xxx">
 51 | 
 52 | <!-- INVALID: should throw a compile time error -->
 53 | ```
 54 | 
 55 | Note that `v-bind:aaa.sync="xxx"` does _not_ currently throw a compile time error, though it probably should.
 56 | 
 57 | ### On a component
 58 | 
 59 | ```vue
 60 | <MyComponent v-model="xxx" />
 61 | 
 62 | <!-- would be shorthand for: -->
 63 | 
 64 | <MyComponent
 65 |   :model-value="xxx"
 66 |   @update:model-value="newValue => { xxx = newValue }"
 67 | />
 68 | ```
 69 | 
 70 | ```vue
 71 | <MyComponent v-model:aaa="xxx"/>
 72 | 
 73 | <!-- would be shorthand for: -->
 74 | 
 75 | <MyComponent
 76 |   :aaa="xxx"
 77 |   @update:aaa="newValue => { xxx = newValue }"
 78 | />
 79 | ```
 80 | 
 81 | ### Duplicating the object spread behavior of `v-bind.sync="xxx"`
 82 | 
 83 | The other directives with arguments are `v-bind` and `v-on`. Both of these use their argument-less versions for spreading an object, but `v-model` without an argument is already shorthand `v-model:model-value="xxx"`. I can see a few different options:
 84 | 
 85 | 1. **Change the behavior of `v-model="xxx"` to spread an object, forcing users to write `v-model:model-value="xxx"` for the old behavior.** This would make `v-model`'s behavior more consistent with `v-bind` and `v-on`, but also create another breaking change and make the most common use case more verbose and complex.
 86 | 
 87 | 2. **Add a new modifier (e.g. `.spread`) to `v-model`.** This would minimize breaking changes, but is inconsistent with the object spread behavior of other directives with arguments, potentially causing confusion and making the framework feel more complex overall.
 88 | 
 89 | 3. **Detect and change the behavior for raw object values (e.g. `v-model="{ ...xxx }"`).** This would again minimize breaking changes, but is a little more consistent with the behavior of other directives with arguments, since `v-bind={ ...xxx }"` would have the same effect. I also expect this would be divisive, as some would likely find it very intuitive, while others would find it understandably confusing that using `xxx` creates radically different behavior than `{ ...xxx }`.
 90 | 
 91 | 4. **Simply don't allow object spread with `v-model`.** This avoids the problems of the above two proposals, but has the drawback of making it more difficult for some people to migrate to Vue 3 (though probably a small minority). Templates/JSX that could benefit from the feature would also become much more tedious to write and maintain, in the best case, or unusable (forcing a refactor to a render function using `createElement`/`h`) in the worst case.
 92 | 
 93 | None of these are great options, but I'm probably most in favor of option 2. I'd also love to hear suggestions for other solutions I may have missed.
 94 | 
 95 | ## Drawbacks
 96 | 
 97 | Beyond the inevitable pains with any breaking change, I think the pain for this syntax would be relatively minimal - partly because the `.sync` modifier is not as widely used a feature and also due to the potential easy of migrating users (see adoption strategy below).
 98 | 
 99 | ## Adoption strategy
100 | 
101 | As a breaking change, this could only be introduced in a major version change (v3). However, I think there are a few things we could do to make migrating easier:
102 | 
103 | - Emit a warning when a `.sync` modifier is detected on `v-bind`, linking to this change's entry in the migration guide.
104 | - Using the new migration helper, we should be able to detect and automatically fix 100% of cases where `v-bind` is used with `.sync`.
105 | 
106 | Combined, learning about and migrating even large codebases with heavy `.sync` usage should take only a few minutes.
107 | 


--------------------------------------------------------------------------------
/active-rfcs/0006-slots-unification.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2019-03-12
 2 | - Target Major Version: 3.x
 3 | - Reference Issues: N/A
 4 | - Implementation PR: N/A
 5 | 
 6 | # Summary
 7 | 
 8 | Unify the concepts of normal vs. scoped slots. They are all just slots in v3.
 9 | 
10 | # Motivation
11 | 
12 | - The separation of normal vs. scoped slots is a result of scoped slots being added on later as a new concept, and they have different internal implementations in 2.x. However, this separation is technically unnecessary. Unifying the two can simplify the overall concept of slots.
13 | 
14 | - Component authors using render functions no longer need to worry about handling both  `$slots` and `$scopedSlots`.
15 | 
16 | - Compiling all slots as functions leads to better performance in large component trees.
17 | 
18 |   Quote from 2.6 release announcement:
19 | 
20 |   > Normal slots are rendered during the parent’s render cycle. When a dependency of a slot changes, it causes both the parent and child components to re-render. Scoped slots, on the other hand, are compiled into inline functions and called during the child component’s render cycle. This means any data dependencies relied on by a scoped slot are collected by the child component, resulting in more precise updates. In 2.6, we have introduced an optimization that further ensures parent scope dependency mutations only affect the parent and would no longer force the child component to update if it uses only scoped slots.
21 | 
22 | # Detailed design
23 | 
24 | Slots unification involves two parts:
25 | 
26 | - Syntax unification (shipped in 2.6 as `v-slot`)
27 | 
28 | - Implementation unification: compile all slots as functions.
29 | 
30 |   - `this.$slots` now exposes slots as functions;
31 | 
32 |   - `this.$scopedSlots` removed.
33 | 
34 |   - In 2.x, all slots using `v-slot` syntax are already compiled as functions internally. `this.$scopedSlots` also proxies to normal slots and expose them as functions.
35 | 
36 | ## Usage in Render Functions
37 | 
38 | Existing render function usage will remain supported. When passing children to a component, both VNodes and functions are supported:
39 | 
40 | ``` js
41 | h(Comp, [
42 |   h('div', this.msg)
43 | ])
44 | 
45 | // equivalent:
46 | h(Comp, () => [
47 |   h('div', this.msg)
48 | ])
49 | ```
50 | 
51 | Inside `Comp`, `this.$slots.default` will be a function in both cases and returns the same VNodes. However, the 2nd case will be more performant as `this.msg` will be registered as a dependency of the child component only.
52 | 
53 | Named slots usage has changed - instead of a special `slot` data property on the content nodes, pass them as children via the 3rd argument:
54 | 
55 | ``` js
56 | // 2.x
57 | h(Comp, [
58 |   h('div', { slot: 'foo' }, this.foo),
59 |   h('div', { slot: 'bar' }, this.bar)
60 | ])
61 | 
62 | // 3.0
63 | // Note the `null` is required to avoid the slots object being mistaken
64 | // for props.
65 | h(Comp, null, {
66 |   foo: () => h('div', this.foo),
67 |   bar: () => h('div', this.bar)
68 | })
69 | ```
70 | 
71 | ### Further Manual Optimization
72 | 
73 | Note that when the parent component updates, `Comp` is always forced to also update because without the compile step Vue doesn't have enough information to tell whether `slots` may have changed.
74 | 
75 | The compiler can detect `v-slot` and compile content as functions, but in render functions this won't happen automatically. We may also be able to perform similar optimizations in our JSX babel plugin. But for users writing direct render functions, they need to do it manually in performance sensitive use cases.
76 | 
77 | Slots can be manually annotated so that Vue won't force the child to update when the parent updates:
78 | 
79 | ``` js
80 | h(Comp, null, {
81 |   $stable: true,
82 |   foo: () => h('div', this.foo),
83 |   bar: () => h('div', this.bar)
84 | })
85 | ```
86 | 
87 | # Adoption strategy
88 | 
89 | Majority of the change has already been shipped in 2.6. The only thing left is the removal of `this.$scopedSlots` from the API. In practice, the current `this.$scopedSlots` in 2.6 works exactly like `this.$slots` in 3.0, so the migration can happen in 2 steps:
90 | 
91 | 1. Use `this.$scopedSlots` everywhere in the 2.x codebase;
92 | 2. Replace all `this.$scopedSlots` occurrences with `this.$slots` in 3.0.
93 | 


--------------------------------------------------------------------------------
/active-rfcs/0007-functional-async-api-change.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-04-08
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: N/A
  4 | - Implementation PR: N/A
  5 | 
  6 | # Summary
  7 | 
  8 | - Functional components must be written as plain functions
  9 |   - `{ functional: true }` option removed
 10 |   - `<template functional>` no longer supported
 11 | - Async component must now be created via a dedicated API method
 12 | 
 13 | # Basic example
 14 | 
 15 | ``` js
 16 | import { h } from 'vue'
 17 | 
 18 | const FunctionalComp = props => {
 19 |   return h('div', `Hello! ${props.name}`)
 20 | }
 21 | ```
 22 | 
 23 | ``` js
 24 | import { defineAsyncComponent } from 'vue'
 25 | 
 26 | const AsyncComp = defineAsyncComponent(() => import('./Foo.vue'))
 27 | ```
 28 | 
 29 | # Motivation
 30 | 
 31 | ## Simplify Functional Components
 32 | 
 33 | In 2.x, functional components must be created using the following format:
 34 | 
 35 | ``` js
 36 | const FunctionalComp = {
 37 |   functional: true,
 38 |   render(h) {
 39 |     return h('div', `Hello! ${props.name}`)
 40 |   }
 41 | }
 42 | ```
 43 | 
 44 | This has the following issues:
 45 | 
 46 | - Even when the component needs nothing but the render function, it still needs to use the object with `functional: true`.
 47 | 
 48 | - Some options are supported (e.g. `props` and `inject`) but others are not (e.g. `components`). However, users often expect all options to be supported because it looks so similar to a normal stateful component (especially when they use SFC with `<template functional>`).
 49 | 
 50 | Another aspect of the problem is that we've noticed some users are using functional components solely for performance reasons, e.g. in SFCs with `<template functional>`, and are requesting us to support more stateful component options in functional components. However, I don't think this is something we should invest more time in.
 51 | 
 52 | In v3, the performance difference between stateful and functional components has been drastically reduced and will be insignificant in most use cases. As a result there is no longer a strong incentive to use functional components just for performance, which also no longer justifies the maintenance cost of supporting `<template functional>`. Functional components in v3 should be used primarily for simplicity, not performance.
 53 | 
 54 | # Detailed Design
 55 | 
 56 | In 3.x, we intend to support functional components **only** as plain functions:
 57 | 
 58 | ``` js
 59 | import { h } from 'vue'
 60 | 
 61 | const FunctionalComp = (props, { slots, attrs, emit }) => {
 62 |   return h('div', `Hello! ${props.name}`)
 63 | }
 64 | ```
 65 | 
 66 | - The `functional` option is removed, and object format with `{ functional: true }` is no longer supported.
 67 | 
 68 | - SFCs will no longer support `<template functional>` - if you need anything more than a function, just use a normal component.
 69 | 
 70 | - The function signature has also changed:
 71 |   - `h` is now imported globally.
 72 |   - The function receives two arguments: `props` and a context object that exposes `slots`, `attrs` and `emit`. These are equivalent to their `$`-prefixed equivalents on a stateful component.
 73 | 
 74 | ## Comparison with Old Syntax
 75 | 
 76 | The new function arguments should provide the ability to fully replace the [2.x functional render context](https://vuejs.org/v2/guide/render-function.html#Functional-Components):
 77 | 
 78 | - `props` and `slots` have equivalent values;
 79 | - `data` and `children` are no longer necessary (just use `props` and `slots`);
 80 | - `listeners` will be included in `attrs`;
 81 | - `injections` can be replaced using the new `inject` API (part of [Composition API](https://vue-composition-api-rfc.netlify.com/api.html#provide-inject)):
 82 | 
 83 |   ``` js
 84 |   import { inject } from 'vue'
 85 |   import { themeSymbol } from './ThemeProvider'
 86 | 
 87 |   const FunctionalComp = props => {
 88 |     const theme = inject(themeSymbol)
 89 |     return h('div', `Using theme ${theme}`)
 90 |   }
 91 |   ```
 92 | 
 93 | - `parent` access will be removed. This was an escape hatch for some internal use cases - in userland code, props and injections should be preferred.
 94 | 
 95 | ## Optional Props Declaration
 96 | 
 97 | To make it easier to use for simple cases, 3.x functional components do not require `props` to be declared:
 98 | 
 99 | ```js
100 | const Foo = props => h('div', props.msg)
101 | ```
102 | ``` html
103 | <Foo msg="hello!" />
104 | ```
105 | 
106 | With no explicit props declaration, the first argument `props` will contain everything passed to the component by the parent.
107 | 
108 | ## Explicit Props Declaration
109 | 
110 | To add explicit props declarations, attach `props` to the function itself:
111 | 
112 | ``` js
113 | const FunctionalComp = props => {
114 |   return h('div', `Hello! ${props.name}`)
115 | }
116 | 
117 | FunctionalComp.props = {
118 |   name: String
119 | }
120 | ```
121 | 
122 | ## Async Component Creation
123 | 
124 | The new async component API is discussed in [its own dedicated RFC](https://github.com/vuejs/rfcs/pull/148).
125 | 
126 | # Drawbacks
127 | 
128 | - Migration cost
129 | 
130 | # Alternatives
131 | 
132 | N/A
133 | 
134 | # Adoption strategy
135 | 
136 | - For functional components, a compatibility mode can be provided for one-at-a-time migration.
137 | 
138 | - SFCs using `<template functional>` should be converted to normal SFCs.
139 | 


--------------------------------------------------------------------------------
/active-rfcs/0009-global-api-change.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-04-08
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: N/A
  4 | - Implementation PR: N/A
  5 | 
  6 | # Summary
  7 | 
  8 | Re-design app bootstrapping and global API.
  9 | 
 10 | - Global APIs that globally mutate Vue's behavior are now moved to **app instances** created by the new `createApp` method, and their effects are now scoped to that app instance only.
 11 | 
 12 | - Global APIs that are do not mutate Vue's behavior (e.g. `nextTick` and the APIs proposed in [Advanced Reactivity API](https://github.com/vuejs/rfcs/pull/22)) are now named exports as specified in [the Global API Treeshaking RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0004-global-api-treeshaking.md).
 13 | 
 14 | # Basic example
 15 | 
 16 | ## Before
 17 | 
 18 | ``` js
 19 | import Vue from 'vue'
 20 | import App from './App.vue'
 21 | 
 22 | Vue.config.ignoredElements = [/^app-/]
 23 | Vue.use(/* ... */)
 24 | Vue.mixin(/* ... */)
 25 | Vue.component(/* ... */)
 26 | Vue.directive(/* ... */)
 27 | 
 28 | Vue.prototype.customProperty = () => {}
 29 | 
 30 | new Vue({
 31 |   render: h => h(App)
 32 | }).$mount('#app')
 33 | ```
 34 | 
 35 | ## After
 36 | 
 37 | ``` js
 38 | import { createApp } from 'vue'
 39 | import App from './App.vue'
 40 | 
 41 | const app = createApp(App)
 42 | 
 43 | app.config.isCustomElement = tag => tag.startsWith('app-')
 44 | app.use(/* ... */)
 45 | app.mixin(/* ... */)
 46 | app.component(/* ... */)
 47 | app.directive(/* ... */)
 48 | 
 49 | app.config.globalProperties.customProperty = () => {}
 50 | 
 51 | app.mount(App, '#app')
 52 | ```
 53 | 
 54 | # Motivation
 55 | 
 56 | Some of Vue's current global API and configurations permanently mutate global state. This leads to a few problems:
 57 | 
 58 | - Global configuration makes it easy to accidentally pollute other test cases during testing. Users need to carefully store original global configuration and restore it after each test (e.g. resetting `Vue.config.errorHandler`). Some APIs (e.g. `Vue.use`, `Vue.mixin`) don't even have a way to revert their effects. This makes tests involving plugins particularly tricky.
 59 | 
 60 |   - `vue-test-utils` has to implement a special API `createLocalVue` to deal with this
 61 | 
 62 | - This also makes it difficult to share the same copy of `Vue` between multiple "apps" on the same page, but with different global configurations:
 63 | 
 64 |   ``` js
 65 |   // this affects both root instances
 66 |   Vue.mixin({ /* ... */ })
 67 | 
 68 |   const app1 = new Vue({ el: '#app-1' })
 69 |   const app2 = new Vue({ el: '#app-2' })
 70 |   ```
 71 | 
 72 | # Detailed design
 73 | 
 74 | Technically, Vue 2 doesn't have the concept of an "app". What we define as an app is simply a root Vue instance created via `new Vue()`. Every root instance created from the same `Vue` constructor shares the same global configuration.
 75 | 
 76 | In this proposal we introduce a new global API, `createApp`:
 77 | 
 78 | ``` js
 79 | import { createApp } from 'vue'
 80 | 
 81 | const app = createApp({
 82 |   /* root component definition */
 83 | })
 84 | ```
 85 | 
 86 | Calling `createApp` returns an **app instance**. An app instance provides an **app context**. The entire component tree mounted by the app instance share the same app context, which provides the configurations that were previously "global" in Vue 2.x.
 87 | 
 88 | ## Global API Mapping
 89 | 
 90 | An app instance exposes a subset of the current global APIs. The rule of thumb is any APIs that globally mutate Vue's behavior are now moved to the app instance. These include:
 91 | 
 92 | - Global configuration
 93 |   - `Vue.config` -> `app.config`
 94 |     - `config.productionTip`: removed. ([details](#remove-configproductiontip))
 95 |     - `config.ignoredElements` -> `config.isCustomElement`. ([details](#configignoredelements---configiscustomelement))
 96 |     - `config.keyCodes`: removed. ([details](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0014-drop-keycode-support.md))
 97 |     - `config.optionMergeStrategies`: see [details](#configoptionmergestrategies-behavior-change) for behavior adjustments.
 98 | - Asset registration APIs
 99 |   - `Vue.component` -> `app.component`
100 |   - `Vue.directive` -> `app.directive`
101 | - Behavior Extension APIs
102 |   - `Vue.mixin` -> `app.mixin`
103 |   - `Vue.use` -> `app.use`
104 | 
105 | All other global APIs that do not globally mutate behavior are now named exports as proposed in [Global API Treeshaking](https://github.com/vuejs/rfcs/pull/19).
106 | 
107 | The only exception is `Vue.extend`. Since the global `Vue` is no longer a new-able constructor, `Vue.extend` no longer makes sense in terms of constructor extension.
108 | 
109 | - For extending a base component, the `extends` option should be used instead.
110 | - For TypeScript type-inference, use the new `defineComponent` global API:
111 | 
112 |   ``` ts
113 |   import { defineComponent} from 'vue'
114 | 
115 |   const App = defineComponent({
116 |     /* Type inference provided */
117 |   })
118 |   ```
119 | 
120 |   Note that implementation-wise `defineComponent` does nothing - it simply returns the object passed to it. However, in terms of typing, the returned value has a synthetic type of a constructor for manual render function, TSX and IDE tooling support. This mismatch is an intentional trade-off.
121 | 
122 | ## Mounting App Instance
123 | 
124 | The app instance can mount a root component with the `mount` method. It works similarly to the 2.x `vm.$mount()` method and returns the mounted root component instance:
125 | 
126 | ``` js
127 | const rootInstance = app.mount(App, '#app')
128 | ```
129 | 
130 | The `mount` method can also accept props to be passed to the root component via the third argument:
131 | 
132 | ``` js
133 | app.mount(App, '#app', {
134 |   // props to be passed to root component
135 | })
136 | ```
137 | 
138 | ### Mounting Behavior Difference from 2.x
139 | 
140 | When using the compiler-included build and mounting a root component with no template of its own, Vue will attempt to use the mount target element's content as template. Note the differences between the 3.x behavior and 2.x:
141 | 
142 | - In 2.x, the root instance uses target element's `outerHTML` as template and replaces target element itself.
143 | 
144 | - In 3.x, the root instance uses target element's `innerHTML` as template and only replaces target element's children.
145 | 
146 | In most cases this should have no effect on how your app behaves, with the only side effect being that if the target element contains multiple children, the root instance will be mounted as a fragment and its `this.$el` will be pointing to the starting anchor node of the fragment (a DOM Comment node).
147 | 
148 | In Vue 3, due to the availability of Fragments, it is recommended to use template refs for direct access to DOM nodes instead of relying on `this.$el`.
149 | 
150 | ## Provide / Inject
151 | 
152 | An app instance can also provide dependencies that can be injected by any component inside the app:
153 | 
154 | ``` js
155 | // in the entry
156 | app.provide({
157 |   [ThemeSymbol]: theme
158 | })
159 | 
160 | // in a child component
161 | export default {
162 |   inject: {
163 |     theme: {
164 |       from: ThemeSymbol
165 |     }
166 |   },
167 |   template: `<div :style="{ color: theme.textColor }" />`
168 | }
169 | ```
170 | 
171 | This is similar to using the `provide` option in a 2.x root instance.
172 | 
173 | ## Remove `config.productionTip`
174 | 
175 | In 3.0, the "use production build" tip will only show up when using the "dev + full build" (the build that includes the runtime compiler and has warnings).
176 | 
177 | For ES modules builds, since they are used with bundlers, and in most cases a CLI or boilerplate would have configured the production env properly, this tip will no longer show up.
178 | 
179 | ## `config.ignoredElements` -> `config.isCustomElement`
180 | 
181 | This config option was introduced with the intention to support native custom elements, so the renaming better conveys what it does. The new option also expects a function which provides more flexibility than the old string / RegExp version:
182 | 
183 | ``` js
184 | // before
185 | Vue.config.ignoredElements = ['my-el', /^ion-/]
186 | 
187 | // after
188 | const app = Vue.createApp({ /* ... */ })
189 | app.config.isCustomElement = tag => tag.startsWith('ion-')
190 | ```
191 | 
192 | **Important:** in 3.0, the check of whether an element is a component or not has been moved to the template compilation phase, therefore this config option is only respected when using the runtime compiler. If you are using the runtime-only build, `isCustomElement` must be passed to `@vue/compiler-dom` in the build setup instead - for example, via the [`compilerOptions` option in `vue-loader`](https://vue-loader.vuejs.org/options.html#compileroptions).
193 | 
194 | - If `config.isCustomElement` is assigned to when using a runtime-only build, a warning will be emitted instructing the user to pass the option in the build setup instead;
195 | 
196 | - This will be a new top-level option in the Vue CLI config.
197 | 
198 | ## `config.optionMergeStrategies` Behavior Change
199 | 
200 | While still supported, due to Vue 3's internal implementation changes, built-in options no longer need merge strategies, so they are no longer exposed. The default `app.config.optionMergeStrategies` is now an empty object. This means:
201 | 
202 | - Users must now always provide their own merge strategy functions instead of reusing built-in strategies (e.g. you can no longer do `config.optionMergeStrategies.custom = config.optionMergeStrategies.props`)
203 | - It is no longer possible to overwrite merge strategies for built-in options.
204 | 
205 | ## Attaching Globally Shared Instance Properties
206 | 
207 | In 2.x, it was possible to inject globally shared instance properties by simply attaching them to `Vue.prototype`.
208 | 
209 | In Vue 3, since the global `Vue` is no longer a constructor, this is no longer supported. Instead, shared instance properties should be attached to an app instance's `config.globalProperties` instead:
210 | 
211 | ``` js
212 | // Before
213 | Vue.prototype.$http = () => {}
214 | 
215 | // After
216 | const app = createApp()
217 | app.config.globalProperties.$http = () => {}
218 | ```
219 | 
220 | # Drawbacks
221 | 
222 | ## Plugin auto installation
223 | 
224 | Many Vue 2.x libraries and plugins offer auto installation in their UMD builds, for example `vue-router`:
225 | 
226 | ``` html
227 | <script src="https://unpkg.com/vue"></script>
228 | <script src="https://unpkg.com/vue-router"></script>
229 | ```
230 | 
231 | Auto installation relies on calling `Vue.use` which is no longer available. This should be a relatively easy migration, and we can expose a stub for `Vue.use` that emits a warning instead.
232 | 
233 | # Alternatives
234 | 
235 | N/A
236 | 
237 | # Adoption strategy
238 | 
239 | - The transformation is straightforward (as seen in the basic example).
240 | - Moved methods can be replaced with stubs that emit warnings to guide migration.
241 | - A codemod can also be provided.
242 | - `config.ingoredElements` can be supported in the compat build.
243 | - `config.optionMergeStrategies` built-in strategies can be supported in the compat build.
244 | 


--------------------------------------------------------------------------------
/active-rfcs/0011-v-model-api-change.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-04-09
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: vuejs/rfcs#8
  4 | - Implementation PR: N/A
  5 | 
  6 | # Summary
  7 | 
  8 | Adjust `v-model` API when used on custom components.
  9 | 
 10 | This builds on top of #8 (Replace `v-bind`'s `.sync` with a `v-model` argument).
 11 | 
 12 | # Basic example
 13 | 
 14 | # Motivation
 15 | 
 16 | Previously, `v-model="foo"` on components roughly compiles to the following:
 17 | 
 18 | ``` js
 19 | h(Comp, {
 20 |   value: foo,
 21 |   onInput: value => {
 22 |     foo = value
 23 |   }
 24 | })
 25 | ```
 26 | 
 27 | However, this requires the component to always use the `value` prop for binding with `v-model` when the component may want to expose the `value` prop for a different purpose.
 28 | 
 29 | In 2.2 we introduced the `model` component option that allows the component to customize the prop and event to use for `v-model`. However, this still only allows one `v-model` to be used on the component. In practice we are seeing some components that need to sync multiple values, and the other values have to use `v-bind.sync`. We noticed that `v-model` and `v-bind.sync` are fundamentally doing the same thing and can be combined into a single construct by allowing `v-model` to accept arguments (as proposed in #8).
 30 | 
 31 | # Detailed design
 32 | 
 33 | In 3.0, the `model` option will be removed. `v-model="foo"` (without argument) on a component compiles to the following instead:
 34 | 
 35 | ``` js
 36 | h(Comp, {
 37 |   modelValue: foo,
 38 |   'onUpdate:modelValue': value => (foo = value)
 39 | })
 40 | ```
 41 | 
 42 | If the component wants to support `v-model` without an argument, it should expect a prop named `modelValue`. To sync its value back to the parent, the child should emit an event named `"update:modelValue"` (see [Render Function API change](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0008-render-function-api-change.md) for details on the new VNode data structure).
 43 | 
 44 | The default compilation output prefixes the prop and event names with `model` to avoid conflict with common prop names.
 45 | 
 46 | RFC #8 proposes the ability for `v-model` to accept arguments. The argument can be used to denote the prop `v-model` should bind to. `v-model:value="foo"` compiles to:
 47 | 
 48 | ``` js
 49 | h(Comp, {
 50 |   value: foo,
 51 |   'onUpdate:value': value => (foo = value)
 52 | })
 53 | ```
 54 | 
 55 | In this case, the child component expects a `value` prop and emits `"update:value"` to sync.
 56 | 
 57 | Note that this enables multiple `v-model` bindings on the same component, each syncing a different prop, without the need for extra options in the component:
 58 | 
 59 | ``` html
 60 | <InviteeForm
 61 |   v-model:name="inviteeName"
 62 |   v-model:email="inviteeEmail"
 63 | />
 64 | ```
 65 | 
 66 | ## Handling Modifiers
 67 | 
 68 | In 2.x, we have hard-coded support for modifiers like `.trim` on component `v-model`. However, it would be more useful if the component can support custom modfiers. In v3, modifiers added to a component `v-model` will be provided to the component via the `modelModifiers` prop:
 69 | 
 70 | ```html
 71 | <Comp v-model.foo.bar="text" />
 72 | ```
 73 | 
 74 | Will compile to:
 75 | 
 76 | ``` js
 77 | h(Comp, {
 78 |   modelValue: text,
 79 |   'onUpdate:modelValue': value => (text = value),
 80 |   modelModifiers: {
 81 |     foo: true,
 82 |     bar: true
 83 |   }
 84 | })
 85 | ```
 86 | 
 87 | For `v-model` with arguments, the generated prop name will be `arg + "Modifiers"`:
 88 | 
 89 | ```html
 90 | <Comp
 91 |    v-model:foo.trim="text"
 92 |    v-model:bar.number="number" />
 93 | ```
 94 | 
 95 | Will compile to:
 96 | 
 97 | ``` js
 98 | h(Comp, {
 99 |   foo: text,
100 |   'onUpdate:foo': value => (text = value),
101 |   fooModifiers: { trim: true },
102 |   bar: number,
103 |   'onUpdate:bar': value => (bar = value),
104 |   barModifiers: { number: true },
105 | })
106 | ```
107 | 
108 | ## Usage on Native Elements
109 | 
110 | Another aspect of the `v-model` usage is on native elements. In 2.x, the compiler produces different code based on the element type `v-model` is used on. For example, it outputs different prop/event combinations for `<input type="text">` and `<input type="checkbox">`. However, this strategy does not handle dynamic element or input types very well:
111 | 
112 | ``` html
113 | <input :type="dynamicType" v-model="foo">
114 | ```
115 | 
116 | The compiler has no way to guess the correct prop/event combination at compile time, so it has to produce [very verbose code](https://template-explorer.vuejs.org/#%3Cinput%20%3Atype%3D%22foo%22%20v-model%3D%22bar%22%3E) to cover possible cases.
117 | 
118 | In 3.0, `v-model` on native elements produces the exact same output as when used on components. For example, `<input v-model="foo">` compiles to:
119 | 
120 | ``` js
121 | h('input', {
122 |   modelValue: foo,
123 |   'onUpdate:modelValue': value => {
124 |     foo = value
125 |   }
126 | })
127 | ```
128 | 
129 | The module responsible for patching element props for the web platform will then dynamically determine how to actually apply them. This enables the compiler to output much less verbose code.
130 | 
131 | # Drawbacks
132 | 
133 | TODO
134 | 
135 | # Alternatives
136 | 
137 | N/A
138 | 
139 | # Adoption strategy
140 | 
141 | TODO
142 | 
143 | # Unresolved questions
144 | 
145 | ## Usage on Custom Elements
146 | 
147 | Reference: [vuejs/vue#7830](https://github.com/vuejs/vue/issues/7830)
148 | 
149 | In 2.x it is difficult to use `v-model` on native custom elements, because the compiler can't tell a native custom element from a normal Vue component (`Vue.config.ignoredElements` is runtime only). The result is that given a custom element with `v-model`:
150 | 
151 | ``` html
152 | <custom-input v-model="foo"></custom-input>
153 | ```
154 | 
155 | The 2.x compiler produces [code for a Vue component](https://template-explorer.vuejs.org/#%3Ccustom-input%20v-model%3D%22foo%22%3E%3C%2Fcustom-input%3E) instead of the native default `value/input` pair.
156 | 
157 | In 3.0, the compiler will produce exactly the same code for both Vue components and native elements, and a native custom element will be handled properly as a native element.
158 | 
159 | The remaining question is that 3rd party custom elements could have unknown prop/event combinations and do not necessarily follow Vue's sync event naming conventions. For example if a custom element expects to work like a checkbox, Vue has no information on the property to bind to or the event to listen to. One possible way to deal with this is to use the `type` attribute as a hint:
160 | 
161 | ``` html
162 | <custom-input v-model="foo" type="checkbox"></custom-input>
163 | ```
164 | 
165 | This would tell Vue to bind `v-model` using the same logic for `<input type="checkbox">`, using `checked` as the prop and `change` as the event.
166 | 
167 | If the custom element doesn't behave like any existing input type, then it's probably better off to use explicit `v-bind` and `v-on` bindings.
168 | 


--------------------------------------------------------------------------------
/active-rfcs/0012-custom-directive-api-change.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-04-09
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: N/A
  4 | - Implementation PR: N/A
  5 | 
  6 | # Summary
  7 | 
  8 | - Re-design custom directive API so that it better aligns with component lifecycle
  9 | 
 10 | - Custom directives usage on components will follow the same rules as discussed in the [Attribute Fallthrough Behavior RFC](https://github.com/vuejs/rfcs/pull/26). It will be controlled by the child component via `v-bind="$attrs"`.
 11 | 
 12 | # Basic example
 13 | 
 14 | ## Before
 15 | 
 16 | ``` js
 17 | const MyDirective = {
 18 |   bind(el, binding, vnode, prevVnode) {},
 19 |   inserted() {},
 20 |   update() {},
 21 |   componentUpdated() {},
 22 |   unbind() {}
 23 | }
 24 | ```
 25 | 
 26 | ## After
 27 | 
 28 | ``` js
 29 | const MyDirective = {
 30 |   beforeMount(el, binding, vnode, prevVnode) {},
 31 |   mounted() {},
 32 |   beforeUpdate() {},
 33 |   updated() {},
 34 |   beforeUnmount() {}, // new
 35 |   unmounted() {}
 36 | }
 37 | ```
 38 | 
 39 | # Motivation
 40 | 
 41 | Make custom directive hook names more consistent with the component lifecycle.
 42 | 
 43 | # Detailed design
 44 | 
 45 | ## Hooks Renaming
 46 | 
 47 | Existing hooks are renamed to map better to the component lifecycle, with some timing adjustments. Arguments passed to the hooks remain unchanged.
 48 | 
 49 | - **new** `created` (called before vnode props are applied to DOM node)
 50 | - `bind` -> `beforeMount` (called after vnode props have been applied to DOM node)
 51 | - `inserted` -> `mounted` (called after children have been inserted into the DOM node, and the DOM node itself has been inserted into parent element)
 52 | - **new** `beforeUpdate` (called before the element itself is updated)
 53 | - ~~`update`~~ *removed, use `updated` instead*
 54 | - `componentUpdated` -> `updated` (called after the element itself and its children have been updated)
 55 | - **new** `beforeUnmount`
 56 | - `unbind` -> `unmounted`
 57 | 
 58 | ## Usage on Components
 59 | 
 60 | In 3.0, with fragments support, components can potentially have more than one root nodes. This creates an issue when a custom directive is used on a component with multiple root nodes.
 61 | 
 62 | To explain the details of how custom directives will work on components in 3.0, we need to first understand how custom directives are compiled in 3.0. For a directive like this:
 63 | 
 64 | ``` html
 65 | <div v-foo="bar"></div>
 66 | ```
 67 | 
 68 | Will roughly compile into this:
 69 | 
 70 | ``` js
 71 | const vFoo = resolveDirective('foo')
 72 | 
 73 | return withDirectives(h('div'), [
 74 |   [vFoo, bar]
 75 | ])
 76 | ```
 77 | 
 78 | Where `vFoo` will be the directive object written by the user, which contains hooks like `mounted` and `updated`.
 79 | 
 80 | `withDirectives` returns a cloned VNode with the user hooks wrapped and injected as vnode lifecycle hooks (see [Render Function API Changes](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0008-render-function-api-change.md#special-reserved-props) for more details):
 81 | 
 82 | ``` js
 83 | {
 84 |   onVnodeMounted(vnode) {
 85 |     // call vFoo.mounted(...)
 86 |   }
 87 | }
 88 | ```
 89 | 
 90 | **As a result, custom directives are fully included as part of a VNode's data. When a custom directive is used on a component, these `onVnodeXXX` hooks are passed down to the component as extraneous props and end up in `this.$attrs`.**
 91 | 
 92 | This also means it's possible to directly hook into an element's lifecycle like this in the template, which can be handy when a custom directive is too involved:
 93 | 
 94 | ``` html
 95 | <div @vnodeMounted="myHook" />
 96 | ```
 97 | 
 98 | This is consistent with the attribute fallthrough behavior discussed in [vuejs/rfcs#26](https://github.com/vuejs/rfcs/pull/26). So, the rule for custom directives on a component will be the same as other extraneous attributes: it is up to the child component to decide where and whether to apply it. When the child component uses `v-bind="$attrs"` on an inner element, it will apply any custom directives used on it as well.
 99 | 
100 | # Drawbacks
101 | 
102 | N/A
103 | 
104 | # Alternatives
105 | 
106 | N/A
107 | 
108 | # Adoption strategy
109 | 
110 | - The renaming should be easy to support in the compat build
111 | - Codemod should also be straightforward
112 | - For directives used on components, the warning on unused `$attrs` as discussed in [Attribute Fallthrough Behavior](https://github.com/vuejs/rfcs/pull/26) should apply as well.
113 | 
114 | # Unresolved questions
115 | 
116 | N/A
117 | 


--------------------------------------------------------------------------------
/active-rfcs/0014-drop-keycode-support.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2019-11-08
 2 | - Target Major Version: 3.x
 3 | - Reference Issues: N/A
 4 | - Implementation PR: N/A
 5 | 
 6 | # Summary
 7 | 
 8 | - Drop support for using numbers (keyCodes) as `v-on` modifiers
 9 | - Remove `config.keyCodes`
10 | 
11 | # Basic example
12 | 
13 | N/A
14 | 
15 | # Motivation
16 | 
17 | In Vue 2.x, `v-on` already supports using the kebab-case version of any valid `KeyboardEvent.key` as a modifier. For example, to trigger the handler only when `event.key === 'PageDown'`:
18 | 
19 | ``` html
20 | <input @keyup.page-down="onArrowUp">
21 | ```
22 | 
23 | This makes number keyCodes and `config.keyCodes` redundant. In addition, [`KeyboardEvent.keyCode` has been deprecated](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode), so it would make sense for Vue to stop supporting it as well.
24 | 
25 | # Drawbacks
26 | 
27 | N/A
28 | 
29 | # Alternatives
30 | 
31 | N/A
32 | 
33 | # Adoption strategy
34 | 
35 | - A codemod can detect usage of number `keyCode` modifier usage and convert it to `key` equivalents.
36 | 
37 | - In compat build, `config.keyCode` can be supported, and the runtime can emit warning when a keyCode alias is matched to allow easy migration.
38 | 


--------------------------------------------------------------------------------
/active-rfcs/0015-remove-filters.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2019-11-12
 2 | - Target Major Version: 3.x
 3 | - Reference Issues: N/A
 4 | - Implementation PR: N/A
 5 | 
 6 | # Summary
 7 | 
 8 | Remove support for [filters](https://vuejs.org/v2/guide/filters.html).
 9 | 
10 | # Basic example
11 | 
12 | ``` html
13 | <!-- before -->
14 | {{ msg | format }}
15 | 
16 | <!-- after -->
17 | {{ format(msg) }}
18 | ```
19 | 
20 | # Motivation
21 | 
22 | - Filters' functionality can be easily replicated with method calls or computed properties so it provides primarily syntactical rather than practical value.
23 | 
24 | - Filters requires a custom micro syntax that breaks the assumption of expressions being "just JavaScript" - which adds to both learning and implementation costs. In fact, it conflicts with JavaScript's own bitwise or operator (`|`) and makes expression parsing more complicated.
25 | 
26 | - Filters also create extra complexity in template IDE support (again due to them not being really JavaScript).
27 | 
28 | # Drawbacks
29 | 
30 | - Filters read a bit nicer when chaining multiple filters vs. calling multiple functions:
31 | 
32 |   ``` js
33 |   msg | uppercase | reverse | pluralize
34 |   // vs
35 |   pluralize(reverse(uppercase(msg)))
36 |   ```
37 | 
38 |   However in practice we find chaining with a count beyond two to be fairly rare, so the readability loss seems acceptable.
39 | 
40 | - Individually importing or defining methods can be a bit more boilerplate-y than globally registered filters. However, global filters are not fundamentally different from registering specially named global helpers on `Vue.prototype`. Such global registration comes with trade-offs: they make the code dependency relationships less explicit, and also makes them difficult to provide type inference for.
41 | 
42 | # Alternatives
43 | 
44 | There is currently a stage 1 proposal for adding the [Pipeline Operator](https://github.com/tc39/proposal-pipeline-operator) to JavaScript, which provides largely similar syntactical convenience:
45 | 
46 | ``` js
47 | let transformedMsg = msg |> uppercase |> reverse |> pluralize
48 | ```
49 | 
50 | Considering there is a possibility of this proposal eventually landing, it is best for a framework like Vue to not provide a similar alternative (especially with syntax that conflicts with existing JavaScript).
51 | 
52 | That said, the proposal is still at stage 1 and hasn't received updates for quite a while, so it is not entirely clear whether it will end up landing, or whether it will land as it is designed right now. It is risky for Vue to adopt it as part of the official API, since we would be forced to introduce breaking changes if the spec ends up changing.
53 | 
54 | In Vue 3, template expression parsing uses [@babel/parser](https://babeljs.io/docs/en/babel-parser), and support for the pipeline operator syntax in templates can be enabled via the `expressionPlugins` compiler option (which is passed on to `@babel/parser` as its [`plugins` option](https://babeljs.io/docs/en/babel-parser#plugins)). Note that the Vue template compiler option only enables the parsing of the syntax - the generated render function needs to be further transpiled by Babel (which is done by default in the new webpack-based setup).
55 | 
56 | # Adoption strategy
57 | 
58 | Filters can be supported in a 2.x compatibility build, with warnings to guide progressive migration.
59 | 


--------------------------------------------------------------------------------
/active-rfcs/0016-remove-inline-templates.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2019-11-14
 2 | - Target Major Version: 3.x
 3 | - Reference Issues: N/A
 4 | - Implementation PR: (leave this empty)
 5 | 
 6 | # Summary
 7 | 
 8 | Remove support for the [inline-template feature](https://vuejs.org/v2/guide/components-edge-cases.html#Inline-Templates).
 9 | 
10 | # Motivation
11 | 
12 | `inline-template` was originally included in Vue to address the cases where Vue is used to progressively enhance a traditionally server-rendered application (e.g. with Rails, Django or Laravel). It allows users to define the template of a child component directly inside a parent's template.
13 | 
14 | The biggest issue with `inline-template` is that it makes template scoping very inconsistent. Without `inline-template`, a simple rule of thumb is that every variable appearing inside a template is either provided by the owner component, or by a directive that explicitly introduces scope variables (e.g. `v-for` and `v-slot`). `inline-template` breaks that assumption by mixing multiple scoping contexts in the same template:
15 | 
16 | ``` html
17 | <div>
18 |   {{ parentMsg }}
19 |   <child-comp inline-template>
20 |     {{ parentMsg }}
21 |   </child-comp>
22 | </div>
23 | ```
24 | 
25 | In a standard component expecting slots, `{{ parentMsg }}` would work intuitively inside the slot content. However with `inline-template`, that is no longer the case. Similarly components with `v-for` + `inline-template` won't work as expected either:
26 | 
27 | ``` html
28 | <child-comp inline-template v-for="item in list">
29 |   {{ item.msg }}
30 | </child-comp>
31 | ```
32 | 
33 | Here the inner template actually has no access to the iterated `item`. It's pointing to `this.item` on the child component instead.
34 | 
35 | # Adoption strategy
36 | 
37 | ## Replacement 1: `<script>` tag
38 | 
39 | Most of the use cases for `inline-template` assumes a no-build-tool setup, where all templates are written directly inside the HTML page. The most straightforward workaround in such cases is using `<script>` with an alternative type:
40 | 
41 | ``` html
42 | <script type="text/html" id="my-comp-template">
43 |   <div>
44 |     {{ hello }}
45 |   </div>
46 | </script>
47 | ```
48 | 
49 | And in the component, target the template using a selector:
50 | 
51 | ``` js
52 | const MyComp = {
53 |   template: '#my-comp-template',
54 |   // ...
55 | }
56 | ```
57 | 
58 | This doesn't require any build setup, works in all browsers, is not subject to in-DOM HTML parsing caveats (e.g. you can use camelCase prop names), and provides proper syntax highlighting in most IDEs. In a traditional server-side framework, these templates can be split out into server template partials (included into the main HTML template) for better maintainability.
59 | 
60 | ## Replacement 2: Default Slot
61 | 
62 | A component previously using `inline-template` can be refactored into using the default slot - which makes the data scoping more explicit while preserving the convenience of writing child content inline:
63 | 
64 | ``` html
65 | <!-- before -->
66 | <my-comp inline-template :msg="parentMsg">
67 |   {{ msg }} {{ childState }}
68 | </my-comp>
69 | 
70 | <!-- after -->
71 | <my-comp v-slot="{ childState }">
72 |   {{ parentMsg }} {{ childState }}
73 | </my-comp>
74 | ```
75 | 
76 | The child, instead of providing no template, should now render the default slot (Note in v3 due to fragment support you can render a slot as the root now):
77 | 
78 | ``` html
79 | <!--
80 |   in child template, render default slot while passing
81 |   in necessary private state of child.
82 | -->
83 | <slot :childState="childState" />
84 | ```
85 | 


--------------------------------------------------------------------------------
/active-rfcs/0017-transition-as-root.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2019-11-29
 2 | - Target Major Version: 3.x
 3 | - Reference Issues: N/A
 4 | - Implementation PR: N/A
 5 | 
 6 | # Summary
 7 | 
 8 | Using `<transition>` as component's root will no longer trigger transitions when the component is toggled from the outside.
 9 | 
10 | # Basic example
11 | 
12 | Before:
13 | 
14 | ``` html
15 | <!-- modal component -->
16 | <template>
17 |   <transition>
18 |     <div class="modal"><slot/></div>
19 |   </transition>
20 | </template>
21 | 
22 | <!-- usage -->
23 | <modal v-if="showModal">hello</modal>
24 | ```
25 | 
26 | After: expose a prop to control the toggle
27 | 
28 | ``` html
29 | <!-- modal component -->
30 | <template>
31 |   <transition>
32 |     <div v-if="show" class="modal"><slot/></div>
33 |   </transition>
34 | </template>
35 | 
36 | <!-- usage -->
37 | <modal :show="showModal">hello</modal>
38 | ```
39 | 
40 | # Motivation
41 | 
42 | The current 2.x behavior worked by accident, but with some quirks. Instead of disabling the usage, we added more fix to make it work because some users were relying on the behavior. However, semantically this usage does not make sense: by definition, the `<transition>` component works by reacting to the toggling of its inner content, not the toggling of itself:
43 | 
44 | ``` html
45 | <!-- this does not work -->
46 | <transition v-if="show">
47 |   <div></div>
48 | </transition>
49 | 
50 | <!-- this is expected usage -->
51 | <transition>
52 |   <div v-if="show"></div>
53 | </transition>
54 | ```
55 | 
56 | In supporting the 2.x behavior, it also created a number of complexities when it comes to determining the `appear` status of the transition.
57 | 
58 | # Detailed design
59 | 
60 | In 3.0, toggling a component with `<transition>` as its root node will no longer trigger the transition. Instead, the component should expose a boolean prop to control the presence of the content inside `<transition>`.
61 | 
62 | # Drawbacks
63 | 
64 | The old behavior cannot be supported simultaneously with the new one in the compat build.
65 | 
66 | # Adoption strategy
67 | 
68 | Reliance on the old behavior can be found through static analysis by detecting root `<transition>` components with no `v-if` or `v-show` directives on its inner content. The migration tool can then guide the user to upgrade these cases.
69 | 


--------------------------------------------------------------------------------
/active-rfcs/0018-transition-class-change.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2019-11-29
 2 | - Target Major Version: 3.x
 3 | - Reference Issues: N/A
 4 | - Implementation PR: N/A
 5 | 
 6 | # Summary
 7 | 
 8 | - Rename the `v-enter` transition class to `v-enter-from`
 9 | - Rename the `v-leave` transition class to `v-leave-from`
10 | - Rename the `v-appear` transition class to `v-appear-from`
11 | 
12 | # Basic example
13 | 
14 | ``` css
15 | /* before */
16 | .v-enter, .v-leave-to{
17 |   opacity: 0;
18 | }
19 | 
20 | /* after */
21 | .v-enter-from, .v-leave-to{
22 |   opacity: 0;
23 | }
24 | ```
25 | 
26 | # Motivation
27 | 
28 | Before v2.1.8, we only had two transition classes each transition direction. For example for the enter transition, we had `v-enter` and `v-enter-active`. In v2.1.8, we introduced `v-enter-to` to address the [timing gap between enter/leave transitions](https://github.com/vuejs/vue/issues/4510), however, for backwards compatibility the `v-enter` name was untouched:
29 | 
30 | ``` css
31 | .v-enter, .v-leave-to {
32 |   opacity: 0;
33 | }
34 | .v-leave, .v-enter-to {
35 |   opacity: 1
36 | }
37 | ```
38 | 
39 | The asymmetry and lack of explicitness in `.v-enter` and `.v-leave` makes these classes a bit mind bending to read and understand. This is why we are proposing to change the above to:
40 | 
41 | ``` css
42 | .v-enter-from, .v-leave-to {
43 |   opacity: 0;
44 | }
45 | .v-leave-from, .v-enter-to {
46 |   opacity: 1
47 | }
48 | ```
49 | 
50 | ...which better indicates what state these classes apply to.
51 | 
52 | # Detailed design
53 | 
54 | - `.v-enter` is renamed to `.v-enter-from`
55 | - `.v-leave` is renamed to `.v-leave-from`
56 | - `.v-appear` is renamed to `.v-appear-from`
57 | - The `<transition>` component's related prop names are also changed:
58 |   - `leave-class` is renamed to `leave-from-class` (in render functions or JSX, can be written as `leaveFromClass`)
59 |   - `enter-class` is renamed to `enter-from-class` (in render functions or JSX, can be written as `enterFromClass`)
60 |   - `appear-class` is renamed to `appear-from-class` (in render functions or JSX, can be written as `appearFromClass`)
61 | 
62 | # Adoption strategy
63 | 
64 | Old class names can be easily supported in the compat build, with warnings to guide migration.
65 | 


--------------------------------------------------------------------------------
/active-rfcs/0019-remove-data-object-declaration.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2020-01-10
 2 | - Target Major Version: 3.x
 3 | - Implementation PR: (leave this empty)
 4 | 
 5 | # Summary
 6 | 
 7 | `data` option accepts two types of declaration: `function` or `object`. The most common is the `function` declaration, because it creates a new state for each instance of the component. `object` declaration on the other hand shares state between all the  instances and works only on a root instance. This RFC primarily focuses on removing `object` declaration for `data`.
 8 | 
 9 | # Motivation
10 | 
11 | There are little or no use-cases for root instances to have a shared state. Even if you encounter such a case it can be achieved using `function` declaration.
12 | Having two types of declaration is not novice-friendly and is confusing without proper examples (which are nonexistent in the current documentation). The additional restriction that `object` declaration is possible only on the root instance is also confusing.
13 | With a unified declaration you could achieve the same result and eliminate the confusing part of it.
14 | 
15 | # Detailed design
16 | 
17 | `object` declaration should no longer be valid and produce an error with an explanation that only `function` declaration is valid for `data` on the root instance. It should also contain a link to an API and migration example.
18 | 
19 | Before, using `object` declaration:
20 | 
21 | ```js
22 | import { createApp, h } from 'vue'
23 | 
24 | createApp().mount({
25 |   data: {
26 |     counter: 1,
27 |   },
28 |   render() {
29 |     return [
30 |       h('span', this.counter),
31 |       h('button', {
32 |         onClick: () => { this.counter++ }
33 |       }),
34 |     ]
35 |   },
36 | }, '#app')
37 | ```
38 | 
39 | After, using `function` declaration.
40 | 
41 | ```js
42 | import { createApp, h } from 'vue'
43 | 
44 | createApp().mount({
45 |   data() {
46 |     return {
47 |       counter: 1,
48 |     }
49 |   },
50 |   render() {
51 |     return [
52 |       h('span', this.counter),
53 |       h('button', {
54 |         onClick: () => { this.counter++ }
55 |       }),
56 |     ]
57 |   },
58 | }, '#app')
59 | ```
60 | 
61 | # Drawbacks
62 | 
63 | Users that work with `object` declaration would require migrating to `function` declaration.
64 | 
65 | It would also not be possible to have top-level shared state.
66 | 
67 | Examples using `object` declaration should be rewritten using `function` declaration.
68 | 
69 | # Adoption strategy
70 | 
71 | Since it's not a common pattern to have an `object` declaration in root instance migration should be fairly easy. The impact of this change is also minimized due to the root mounting API change in v3 (where you always use a root component).
72 | 
73 | Migration itself is straightforward:
74 | 
75 | * Extract shared data into an external object and use it as a property in `data`.
76 | * Rewrite references to the shared data to point to a new shared object.
77 | 
78 | API page should contain an info block describing that `object` declaration is deprecated with a guide on how to migrate.
79 | 
80 | An adapter could be provided to retain backwards compatibility.
81 | 


--------------------------------------------------------------------------------
/active-rfcs/0020-events-api-change.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2020-01-21
 2 | - Target Major Version: 3.x
 3 | - Reference Issues: https://github.com/vuejs/vue/issues/5443 https://github.com/vuejs/vue-next/issues/635
 4 | - Implementation PR: N/A
 5 | 
 6 | # Summary
 7 | 
 8 | Remove `$on`, `$off` and `$once` instance methods. Vue instances no longer implement the event emitter interface.
 9 | 
10 | # Motivation
11 | 
12 | Vue 1.x implemented the component event system similar to that of AngularJS, with `$dispatch` and `$broadcast` where components in a tree can communicate by sending events up and down the tree.
13 | 
14 | In Vue 2, we removed `$dispatch` and `$broadcast` in favor of a more state-driven data flow (props down, events up).
15 | 
16 | With Vue 2's API, `$emit` can be used to trigger event handlers declaratively attached by a parent component (in templates or render functions), but can also be used to trigger handlers attached imperatively via the event emitter API (`$on`, `$off` and `$once`). This is in fact an overload: the full event emitter API isn't a part of the typical inter-component data-flow. They are rarely used, and there are really no strong reason for them to be exposed via component instances. This RFC therefore proposes to remove the `$on`, `$off` and `$once` instance methods.
17 | 
18 | # Adoption strategy
19 | 
20 | In Vue 2, the most common usage of the event emitter API is using an empty Vue instance as an event hub. This can be replaced by using an external library implementing the event emitter interface, for example [mitt](https://github.com/developit/mitt).
21 | 
22 | These methods can also be supported in compatibility builds.
23 | 


--------------------------------------------------------------------------------
/active-rfcs/0021-router-link-scoped-slot.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-04-29
  2 | - Target Major Version: Vue (2.x / 3.x) Vue Router (3.x / 4.x)
  3 | - Reference Issues: https://github.com/vuejs/vue-router/issues/2611,
  4 | - Implementation PR: Implemented in both [v3.x](https://github.com/vuejs/vue-router/commit/e289ddee99fcc3129e65485e32f394c1308bb98b) and v4.x
  5 | 
  6 | # Summary
  7 | 
  8 | - Remove `tag` prop
  9 | - Remove `event` prop
 10 | - Stop automatically assigning click events to inner anchors
 11 | - Add a scoped-slot API
 12 | - Add a `custom` prop to fully customize `router-link`'s rendering
 13 | 
 14 | # Basic example
 15 | 
 16 | ```vue
 17 | <router-link to="/">
 18 |   <Icon>home</Icon> Home
 19 | </router-link>
 20 | ```
 21 | 
 22 | # Motivation
 23 | 
 24 | Current implementation of Router Link has many limitations:
 25 | 
 26 | - Active state customization is not complete ([#2611](https://github.com/vuejs/vue-router/issues/2611)
 27 | - Cannot be integrated with custom components ([#2021](https://github.com/vuejs/vue-router/issues/2021))
 28 | - click event cannot be prevented (through `@click.prevent` nor through a `disabled` attribute [#2098](https://github.com/vuejs/vue-router/pull/2098))
 29 | 
 30 | The idea of this RFC is to solve those issues by providing a scoped slot that allow app developers to easily extend Links based on their applications and to allow library authors to provide an even easier integration with Vue Router.
 31 | 
 32 | # Detailed design
 33 | 
 34 | ## Slot with content
 35 | 
 36 | A simple use case would be slot with content (no nested anchors or buttons)
 37 | 
 38 | ```vue
 39 | <router-link to="/">
 40 |   <Icon>home</Icon> Home
 41 | </router-link>
 42 | ```
 43 | 
 44 | This implementation would:
 45 | 
 46 | - generate an anchor (`a`) element and apply the corresponding properties:
 47 |   - `href` with the destination
 48 |   - `class` with `router-link-active` and/or `router-link-exact-active` (can be changed through prop or global option)
 49 |   - click listener to trigger navigation through `router.push` or `router.replace` with a `event.preventDefault` (except when the link is clicked using a modifier like <kbd>⌘</kbd> or <kbd>Ctrl</kbd>)
 50 | - Put anything passed as the children of the anchor
 51 | - Pass down any attributes that aren't props to the `a` element
 52 | 
 53 | **Breaking changes**:
 54 | 
 55 | - no longer accept a `tag` prop -> use the scoped slot instead (see the point below)
 56 | - no longer accepts `event` -> use the scoped slot instead
 57 | - no longer works as a wrapper automatically looking for the first `a` inside -> use the scoped slot instead
 58 | 
 59 | ## Scoped slot
 60 | 
 61 | A scoped slot would get access to every bit of information needed to provide a custom integration and allows applying the active classes, click listener, links, etc at any level. This would allow a better integration with UI frameworks like Bootstrap (https://getbootstrap.com/docs/4.3/components/navbar/). The idea would be to create a Vue component to avoid the boilerplate like bootstrap-vue does (https://bootstrap-vue.js.org/docs/components/navbar/#navbar)
 62 | 
 63 | ```vue
 64 | <router-link to="/" custom v-slot="{ href, navigate, isActive }">
 65 |   <li :class="{ 'active': isActive }">
 66 |     <a :href="href" @click="navigate">
 67 |       <Icon>home</Icon><span class="xs-hidden">Home</span>
 68 |     </a>
 69 |   </li>
 70 | </router-link>
 71 | ```
 72 | 
 73 | The `custom` prop is necessary to take full control over `router-link`'s rendering: not rendering a wrapping `a` element.
 74 | 
 75 | **Why is a `custom` prop necessary**: in Vue 3, scoped slots and regular slots cannot be differentiated from each other, which means vue router is unable to make the difference between these 3 cases:
 76 | 
 77 | ```vue
 78 | <router-link to="/" v-slot="{ href, navigate, isActive }"></router-link>
 79 | <router-link to="/" v-slot></router-link>
 80 | <router-link to="/">Some Link</router-link>
 81 | ```
 82 | 
 83 | In all three cases we need to render the slot content but `router-link` needs to know if it has to render a wrapping `a` element. In Vue 2, we are able to do so by checking `$scopedSlots` but in Vue 3, only `slots` exists. This means that the behavior is slightly different in Vue Router v3 and Vue Router v4:
 84 | 
 85 | - In v3, the `custom` prop is required (see [Adoption strategy](#adoption-strategy)) alongside `v-slot`. `router-link` will not wrap the slot content with an `a` element.
 86 | - In v4, the `custom` prop is **not** required alongside `v-slot`. It controls whether `router-link` should wrap its slot content with an `a` element or not:
 87 |   ```vue
 88 |   <router-link to="/" v-slot="{ href }">
 89 |   <router-link to="/" custom v-slot="{ href, navigate }">
 90 |     <a :href="href" @click="navigate">{{ href }}</a>
 91 |   </router-link>
 92 |   <!-- both render the same -->
 93 |   <a href="/">/</a>
 94 |   <a href="/">/</a>
 95 |   ```
 96 | 
 97 | ### Accessible variables
 98 | 
 99 | The slot should provide values that are computed inside `router-link`:
100 | 
101 | - `href`: resolved relative url to be added to an anchor tag (contains the base if provided while route.fullPath doesn't)
102 | - `route`: resolved normalized route location from the `to` (same shape as `$route`)
103 | - `navigate`: function to trigger navigation (usually attached to a click). Also calls `preventDefault` if the click is directly pressed.
104 | - `isActive`: true whenever `router-link-active` is applied. Can be modified by `exact` prop
105 | - `isExactActive`: true whenever `router-link-exact-active` is aplied. Can be modified by `exact` prop.
106 | 
107 | ## The removal of the `tag` prop
108 | 
109 | The `tag` prop can be replaced which a scoped slot and make the code clearer while not being exposed to any caveat. Its removal will also lighten the vue-router library.
110 | 
111 | ```vue
112 | <router-link to="/" tag="button">
113 |   <Icon>home</Icon><span class="xs-hidden">Home</span>
114 | </router-link>
115 | ```
116 | 
117 | is equivalent to
118 | 
119 | ```vue
120 | <router-link to="/" custom v-slot="{ navigate, isActive, isExactActive }">
121 |   <button role="link" @click="navigate" :class="{ active: isActive, 'exact-active': isExactActive }">
122 |     <Icon>home</Icon><span class="xs-hidden">Home</span>
123 |   </button>
124 | </router-link>
125 | ```
126 | 
127 | (see above for explanation about the attributes passed to the scoped-slot)
128 | 
129 | # Drawbacks
130 | 
131 | - Whereas it's possible to keep existing behaviour working and only expose a new behaviour with scoped slots, it will still prevent us from fixing existing issues with current implementation. That's why there are some breaking changes, to make things more consistent.
132 | - No access to the default `router-link` classes like `router-link-active` and `router-link-exact-active`.
133 | 
134 | # Alternatives
135 | 
136 | - Keeping `event` prop for convienience
137 | - Use a different named slot instead of a `prop`:
138 | 
139 |   ```vue
140 |   <router-link #custom="{ href }">
141 |     <a :href="href"></a>
142 |   </router-link>
143 | 
144 |   <router-link v-slot:custom="{ href }">
145 |     <a :href="href"></a>
146 |   </router-link>
147 | 
148 |   <router-link custom v-slot="{ href }">
149 |     <a :href="href"></a>
150 |   </router-link>
151 |   ```
152 | 
153 |   The adoption strategy in this case would be similar but the warning would tell the user to use a different slot instead of a prop named `custom`
154 | 
155 | - Create a new component like `router-link-custom` to differentiate the behavior. This solution is however heavier (in terms of size) than a prop or a different named slot. It is also less suitable than a prop because we are only changing a behavior of the component. The difference between the two components woud be too small to justify a whole new component.
156 | 
157 | # Adoption strategy
158 | 
159 | - Document new slot behaviour based on examples
160 | - Deprecate `tag` and `event` with a message in v3 and link to documentation, then remove in v4
161 | - In v3, if no `custom` prop is provided when using a scoped slot, warn the user to use the `custom` prop
162 | 


--------------------------------------------------------------------------------
/active-rfcs/0022-router-merge-meta-routelocation.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2020-03-12
 2 | - Target Major Version: Router 4.x
 3 | - Reference Issues: N/A
 4 | - Implementation PR:
 5 | 
 6 | # Summary
 7 | 
 8 | When creating routes, you can attach arbitrary data with the `meta` property:
 9 | 
10 | ```js
11 | { path: '/profile', meta: { requiresAuth: true }}
12 | ```
13 | 
14 | It's then accessible in navigation guards and on `$route`:
15 | 
16 | ```js
17 | router.beforeEach((to, from, next) => {
18 |   if (to.meta.requiresAuth && !auth.loggedIn()) next('/login')
19 |   else next()
20 | })
21 | ```
22 | 
23 | However, when dealing with nested routes, `meta` will contain only the matched route `meta`. You can still go through the array of `matched` records like [pointed out in the documentation](https://router.vuejs.org/guide/advanced/meta.html#route-meta-fields):
24 | 
25 | ```js
26 | router.beforeEach((to, from, next) => {
27 |   if (to.matched.some(record => record.meta.requiresAuth))
28 |   // ...
29 | })
30 | ```
31 | 
32 | My proposal is to merge all matched routes meta, from parent to child so we can do `to.meta.requiresAuth`. I believe this is what Nuxt does but I couldn't find a link in the docs.
33 | 
34 | # Basic example
35 | 
36 | Given a nested route:
37 | 
38 | ```js
39 | {
40 |   path: '/parent',
41 |   meta: { requiresAuth: true, isChild: false },
42 |   children: [
43 |     { path: 'child', meta: { isChild: true }}
44 |   ]
45 | }
46 | ```
47 | 
48 | Navigating to `/parent/child` should generate a route with the following `meta` property:
49 | 
50 | ```js
51 | { requiresAuth: true, isChild: true }
52 | ```
53 | 
54 | # Motivation
55 | 
56 | Most of the time, merging the `meta` property is what we need. I've never seen a case where I exclusively needed the most nested route `meta` property.
57 | 
58 | This would remove the need of doing `to.matched.some` to check if a `meta` field is present. Instead, it will be only necessary to use it to check overriden `meta` properties.
59 | 
60 | # Detailed design
61 | 
62 | The `meta` property is merged only at the first level, like `Object.assign` and the _spread operator_:
63 | 
64 | ```js
65 | {
66 |   path: '/parent',
67 |   meta: { nested: { a: true } },
68 |   children: [
69 |     { path: 'child', meta: { nested: { b: true }}}
70 |   ]
71 | }
72 | ```
73 | 
74 | yields the following `meta` object when at `/parent/child`:
75 | 
76 | ```js
77 | {
78 |   nested: {
79 |     b: true
80 |   }
81 | }
82 | ```
83 | 
84 | # Drawbacks
85 | 
86 | - This is technically a breaking change
87 | 


--------------------------------------------------------------------------------
/active-rfcs/0023-scoped-styles-changes.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-01-21
  2 | - Target Major Version: 2.x, 3.x
  3 | - Reference Issues: N/A
  4 | - Implementation PR: N/A
  5 | 
  6 | # Summary
  7 | 
  8 | Provide more consistent custom CSS extensions in Single File Component scoped styles.
  9 | 
 10 | # Basic example
 11 | 
 12 | ``` html
 13 | <style scoped>
 14 | /* deep selectors */
 15 | ::v-deep(.foo) {}
 16 | /* shorthand */
 17 | :deep(.foo) {}
 18 | 
 19 | /* targeting slot content */
 20 | ::v-slotted(.foo) {}
 21 | /* shorthand */
 22 | :slotted(.foo) {}
 23 | 
 24 | /* one-off global rule */
 25 | ::v-global(.foo) {}
 26 | /* shorthand */
 27 | :global(.foo) {}
 28 | </style>
 29 | ```
 30 | 
 31 | # Motivation
 32 | 
 33 | Vue SFC scoped styles makes the CSS apply to the current component only. There are a number of cases that users commonly run into that can be improved.
 34 | 
 35 | ## Deep Selectors
 36 | 
 37 | Sometimes we may want to explicitly make a rule target child components.
 38 | 
 39 | Originally we supported the `>>>` combinator to make the selector "deep". However, some CSS pre-processors such as SASS has issues parsing it since this is not an official CSS combinator.
 40 | 
 41 | We later switched to `/deep/`, which was once an actual proposed addition to CSS (and even natively shipped in Chrome), but later dropped. This caused confusion for some users, since they worry that using `/deep/` in Vue SFCs would make their code not supported in browsers that have dropped the feature. However, just like `>>>`, `/deep/` is only used as a compile-time hint by Vue's SFC compiler to rewrite the selector, and is removed in the final CSS.
 42 | 
 43 | To avoid the confusion of the dropped `/deep/` combinator, we introduced yet another custom combinator, `::v-deep`, this time being more explicit that this is a Vue-specific extension, and using the pseudo-element syntax so that any pre-processor should be able to parse it.
 44 | 
 45 | The previous versions of the deep combinator are still supported for compatibility reasons in the current [Vue 2 SFC compiler](https://github.com/vuejs/component-compiler-utils), which again, can be confusing to users. In v3, we are deprecating the support for `>>>` and `/deep/`.
 46 | 
 47 | As we were working on the new SFC compiler for v3, we noticed that CSS pseudo elements are in fact semantically NOT [combinators](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors/Combinators). It is more consistent with idiomatic CSS for pseudo elements to accept arguments instead, so we are also making `::v-deep()` work that way. If you don't care about the explicit `v-` prefix, you can also use the shorter `:deep()` variant, which works exactly the same.
 48 | 
 49 | The current usage of `::v-deep` as a combinator is still supported, however it is considered deprecated and will raise a warning.
 50 | 
 51 | ## Targeting / Avoiding Slot Content
 52 | 
 53 | Currently, slot content passed in from the parent are affected by both the parent's scoped styles AND the child's scoped styles. There is no way to author rules that explicitly target slot content only, or ones that do not affect slot content.
 54 | 
 55 | In v3, we intend to make child scoped styles NOT affecting slot content by default. To explicitly target slot content, the `::v-slotted()` (shorthand: `:slotted()`) pseudo element can be used.
 56 | 
 57 | ## One-Off Global Rules
 58 | 
 59 | Currently to add a global CSS rule we need to use a separate unscoped `<style>` block. We are introducing a new `::v-global()` (shorthand: `:global()`) pseudo element for one-off global rules.
 60 | 
 61 | ---
 62 | 
 63 | > We are also aware that many users want to be able to use component props or state in the CSS of single-file components. We do have plans to support that but it will be in a separate RFC.
 64 | 
 65 | # Detailed design
 66 | 
 67 | - `>>>` and `/deep/` support are deprecated.
 68 | 
 69 | - `::v-deep` usage as a combinator is deprecated:
 70 | 
 71 |   ``` css
 72 |   /* DEPRECATED */
 73 |   ::v-deep .bar {}
 74 |   ```
 75 | 
 76 |   Instead, use it as a pseudo element that accepts another selector as argument:
 77 | 
 78 |   ``` css
 79 |   ::v-deep(.bar) {}
 80 |   ```
 81 | 
 82 |   The above compiles to:
 83 | 
 84 |   ``` css
 85 |   [v-data-xxxxxxx] .bar {}
 86 |   ```
 87 | 
 88 | - Slot content passed in from the parent no longer gets affected by child scoped styles by default. Instead, the child now needs to use the new `::v-slotted()` pseudo element to specifically target slot content:
 89 | 
 90 |   ``` css
 91 |   ::v-slotted(.foo) {}
 92 |   ```
 93 | 
 94 |   Compiles to:
 95 | 
 96 |   ``` css
 97 |   .foo[v-data-xxxxxxx-s] {}
 98 |   ```
 99 | 
100 |   Notice the `-s` postfix which makes it target slot content only.
101 | 
102 | - New pseudo element `::v-global()` can be used to apply global rules inside a `<style scoped>` block:
103 | 
104 |   ``` css
105 |   ::v-global(.foo) {}
106 |   ```
107 | 
108 |   Compiles to:
109 | 
110 |   ``` css
111 |   .foo {}
112 |   ```
113 | 
114 | - The [test cases of `@vue/compiler-sfc`](https://github.com/vuejs/vue-next/blob/master/packages/compiler-sfc/__tests__/compileStyle.spec.ts) can be used as a reference for the compilation transform details.
115 | 
116 | # Adoption strategy
117 | 
118 | All previous usage of deep selectors can be supported with deprecation warnings. We will remove the support in a future release when most users have completed the migration.
119 | 
120 | The slot content behavior change should technically lead to more decoupled styling between parent and child components, however the behavior can indeed break existing styles that rely on child styles applied to slot content. We may need to provide an option to preserve the old behavior.
121 | 
122 | # Unresolved questions
123 | 
124 | We are not sure about how much the slot styling behavior change would affect existing components - any feedback would be appreciated.
125 | 


--------------------------------------------------------------------------------
/active-rfcs/0024-attribute-coercion-behavior.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-01-30
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: [#8731](https://github.com/vuejs/vue/issues/8731) [#8735](https://github.com/vuejs/vue/pull/8735) [#9397](https://github.com/vuejs/vue/issues/9397) [#11053](https://github.com/vuejs/vue/issues/11053)
  4 | - Implementation PR:
  5 | 
  6 | # Summary
  7 | 
  8 | - Drop the internal concept of enumerated attributes and treat those attributes the same as normal non-boolean attributes.
  9 | - No longer removes attribute if value is boolean `false`. Instead, it's set as `attr="false"` instead. To remove the attribute, use `null` or `undefined`.
 10 | 
 11 | # Motivation
 12 | 
 13 | In 2.x, we have the following strategies for coercing `v-bind` values:
 14 | 
 15 | - For some attribute/element pairs, Vue is always using the corresponding IDL attribute (property): [like `value` of `<input>`, `<select>`, `<progress>`, etc](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L11-L18).
 16 | 
 17 | - For “[boolean attributes](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L33-L40)” and [xlinks](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L44-L46), Vue removes them if they are “falsy” ([`undefined`, `null` or `false`](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L52-L54)) and adds them otherwise (see [here](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/runtime/modules/attrs.js#L66-L77) and [here](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/runtime/modules/attrs.js#L81-L85)).
 18 | 
 19 | - For “[enumerated attributes](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L20)” (currently `contenteditable`, `draggable` and `spellcheck`), Vue tries to [coerce](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/util/attrs.js#L24-L31) them to string (with special treatment for `contenteditable` for now, to fix [vuejs/vue#9397](https://github.com/vuejs/vue/issues/9397)).
 20 | 
 21 | - For other attributes, we remove “falsy” values (`undefined`, `null`, or `false`) and set other values as-is (see [here](https://github.com/vuejs/vue/blob/bad3c326a3f8b8e0d3bcf07917dc0adf97c32351/src/platforms/web/runtime/modules/attrs.js#L92-L113)).
 22 | 
 23 | In 2.x we modeled the concept of “enumerated attributes” as if they can only accept `'true'` or `'false'`, which is technically flawed. This also make them behave differently from other non-boolean attributes which led to confusion. The following table describes how Vue coerce “enumerated attributes” differently with normal non-boolean attributes:
 24 | 
 25 | | Binding expr. | `foo` <sup>normal</sup> | `draggable` <sup>enumerated</sup> |
 26 | | - | - | - |
 27 | | `:attr="null"` | / | `draggable="false"` |
 28 | | `:attr="undefined"` | / | / |
 29 | | `:attr="true"` | `foo="true"` | `draggable="true"` |
 30 | | `:attr="false"` | / | `draggable="false"` |
 31 | | `:attr="0"` | `foo="0"` | `draggable="true"` |
 32 | | `attr=""` | `foo=""` | `draggable="true"` |
 33 | | `attr="foo"` | `foo="foo"` | `draggable="true"` |
 34 | | `attr` | `foo=""` | `draggable="true"` |
 35 | 
 36 | We can see from the table above, current implementation coerces `true` to `'true'` but removes the attribute if it's `false`. This also led to inconsistency and required users to manually coerce boolean values to string in very common use cases like `aria-*` attributes like `aria-selected`, `aria-hidden`, etc.
 37 | 
 38 | # Detailed design
 39 | 
 40 | - We intend to drop this internal concept of “enumerated attributes” and treat them as normal non-boolean HTML attributes.
 41 | 
 42 |   This solves the inconsistency between normal non-boolean attributes and “enumerated attributes”. It also made it possible to use value other than `'true'` and `'false'`, or even keywords yet to come, for attributes like `contenteditable`.
 43 | 
 44 | - For non-boolean attributes, stop removing them if they are `false` and coerce them to `'false'` instead.
 45 | 
 46 |   This solves the inconsistency between `true` and `false` and makes outputing `aria-*` attributes easier.
 47 | 
 48 | The following table describes the new behavior:
 49 | 
 50 | | Binding expr. | `foo` <sup>normal</sup> | `draggable` <sup>enumerated</sup> |
 51 | | - | - | - |
 52 | | `:attr="null"` | / | / <sup>†</sup> |
 53 | | `:attr="undefined"` | / | / |
 54 | | `:attr="true"` | `foo="true"` | `draggable="true"` |
 55 | | `:attr="false"` | `foo="false"` <sup>†</sup> | `draggable="false"` |
 56 | | `:attr="0"` | `foo="0"` | `draggable="0"` <sup>†</sup> |
 57 | | `attr=""` | `foo=""` | `draggable=""` <sup>†</sup> |
 58 | | `attr="foo"` | `foo="foo"` | `draggable="foo"` <sup>†</sup> |
 59 | | `attr` | `foo=""` | `draggable=""` <sup>†</sup> |
 60 | 
 61 | <small>†: changed</small>
 62 | 
 63 | Coercion for boolean attributes is kept untouched.
 64 | 
 65 | # Drawbacks
 66 | 
 67 | This proposal is introducing the following breaking changes:
 68 | 
 69 | - For “enumerated attributes”:
 70 | 
 71 |   - `null` will remove the attribute instead of producing `'false'`.
 72 |   - Numbers and string values other than `'true'` and `'false'` won't be coerced to `'true'` any more. (The old behavior shouldn't have been working anyway.)
 73 | 
 74 | - For all non-boolean attributes, `false` values won't be removed any more and will be coerced to `'false'`.
 75 | 
 76 | The most major breakage here is that users should stop relying on `false` values to remove attributes, instead they are required to use `null` or `undefined` to do that. As boolean attributes are not affected, this change mostly affects enumerated attributes where `'false'` value and absence of the attribute result in different element state. eg. `aria-checked`. It may also affect CSS selectors like `[foo]`.
 77 | 
 78 | # Alternatives
 79 | 
 80 | N/A
 81 | 
 82 | # Adoption strategy
 83 | 
 84 | It's unlikely that a codemod can help in this case. We shall provide detailed information in our migration guide and document the coercion behavior in 3.x docs.
 85 | 
 86 | ## Enumerated attributes
 87 | 
 88 | The absence of an enumerated attribute and `attr="false"` may produce different IDL attribute values (which will reflect the actual state), described as follows:
 89 | 
 90 | | Absent enumerated attr | IDL attr & value |
 91 | | - | - |
 92 | | `contenteditable` | `contentEditable` &rarr; `'inherit'` |
 93 | | `draggable` | `draggable` &rarr; `false` |
 94 | | `spellcheck` | `spellcheck` &rarr; `true` |
 95 | 
 96 | To keep the old behavior work, and as we will be coercing `false` to `'false'`, in 3.x Vue developers need to make `v-bind` expression resolve to `false` or `'false'` for `contenteditable` and `spellcheck`.
 97 | 
 98 | In 2.x, invalid values were coerced to `'true'` for enumerated attributes. This was usually unintended and unlikely to be relied upon on a large scale. In 3.x `true` or `'true'` should be explicitly specified.
 99 | 
100 | ## Coercing `false` to `'false'` instead of removing the attribute
101 | 
102 | In 3.x, `null` or `undefined` should be used to explicitly remove an attribute.
103 | 
104 | ## Comparison between 2.x & 3.x behavior
105 | 
106 | <table>
107 |   <thead>
108 |     <tr>
109 |       <th>Attribute</th>
110 |       <th><code>v-bind</code> value <sup>2.x</sup></th>
111 |       <th><code>v-bind</code> value <sup>3.x</sup></th>
112 |       <th>HTML output</th>
113 |     </tr>
114 |   </thead>
115 |   <tbody>
116 |     <tr>
117 |       <td rowspan="3">2.x “Enumerated attrs”<br><small>i.e. <code>contenteditable</code>, <code>draggable</code> and <code>spellcheck</code>.</small></td>
118 |       <td><code>undefined</code>, <code>false</code></td>
119 |       <td><code>undefined</code>, <code>null</code></td>
120 |       <td><i>removed</i></td>
121 |     </tr>
122 |     <tr>
123 |       <td>
124 |         <code>true</code>, <code>'true'</code>, <code>''</code>, <code>1</code>,
125 |         <code>'foo'</code>
126 |       </td>
127 |       <td><code>true</code>, <code>'true'</code></td>
128 |       <td><code>"true"</code></td>
129 |     </tr>
130 |     <tr>
131 |       <td><code>null</code>, <code>'false'</code></td>
132 |       <td><code>false</code>, <code>'false'</code></td>
133 |       <td><code>"false"</code></td>
134 |     </tr>
135 |     <tr>
136 |       <td rowspan="2">Other non-boolean attrs<br><small>eg. <code>aria-checked</code>, <code>tabindex</code>, <code>alt</code>, etc.</small></td>
137 |       <td><code>undefined</code>, <code>null</code>, <code>false</code></td>
138 |       <td><code>undefined</code>, <code>null</code></td>
139 |       <td><i>removed</i></td>
140 |     </tr>
141 |     <tr>
142 |       <td><code>'false'</code></td>
143 |       <td><code>false</code>, <code>'false'</code></td>
144 |       <td><code>"false"</code></td>
145 |     </tr>
146 |   </tbody>
147 | </table>
148 | 
149 | # Unresolved questions
150 | 
151 | N/A
152 | 


--------------------------------------------------------------------------------
/active-rfcs/0026-async-component-api.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-03-25
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: https://github.com/vuejs/rfcs/pull/28
  4 | 
  5 | # Summary
  6 | 
  7 | Introduce a dedicated API for defining async components.
  8 | 
  9 | # Basic example
 10 | 
 11 | ```js
 12 | import { defineAsyncComponent } from "vue"
 13 | 
 14 | // simple usage
 15 | const AsyncFoo = defineAsyncComponent(() => import("./Foo.vue"))
 16 | 
 17 | // with options
 18 | const AsyncFooWithOptions = defineAsyncComponent({
 19 |   loader: () => import("./Foo.vue"),
 20 |   loadingComponent: LoadingComponent,
 21 |   errorComponent: ErrorComponent,
 22 |   delay: 200,
 23 |   timeout: 3000
 24 | })
 25 | ```
 26 | 
 27 | # Motivation
 28 | 
 29 | Per changes introduced in [RFC-0008: Render Function API Change](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0008-render-function-api-change.md), in Vue 3 plain functions are now treated as functional components. Async components must now be explicitly defined via an API method.
 30 | 
 31 | # Detailed design
 32 | 
 33 | ## Simple Usage
 34 | 
 35 | ```js
 36 | import { defineAsyncComponent } from "vue"
 37 | 
 38 | // simple usage
 39 | const AsyncFoo = defineAsyncComponent(() => import("./Foo.vue"))
 40 | ```
 41 | 
 42 | `defineAsyncComponent` can accept a loader function that returns a Promise resolving to the actual component.
 43 | 
 44 | - If the resolved value is an ES module, the `default` export of the module will automatically be used as the component.
 45 | 
 46 | - **Difference from 2.x:** Note that the loader function no longer receives the `resolve` and `reject` arguments like in 2.x - a Promise must always be returned.
 47 | 
 48 |   For code that relies on custom `resolve` and `reject` in the loader function, the conversion is straightforward:
 49 | 
 50 |   ```js
 51 |   // before
 52 |   const Foo = (resolve, reject) => {
 53 |     /* ... */
 54 |   }
 55 | 
 56 |   // after
 57 |   const Foo = defineAsyncComponent(() => new Promise((resolve, reject) => {
 58 |     /* ... */
 59 |   }))
 60 |   ```
 61 | 
 62 | ## Options Usage
 63 | 
 64 | ```js
 65 | import { defineAsyncComponent } from "vue"
 66 | 
 67 | const AsyncFooWithOptions = defineAsyncComponent({
 68 |   loader: () => import("./Foo.vue"),
 69 |   loadingComponent: LoadingComponent,
 70 |   errorComponent: ErrorComponent,
 71 |   delay: 100, // default: 200
 72 |   timeout: 3000, // default: Infinity
 73 |   suspensible: false, // default: true
 74 |   onError(error, retry, fail, attempts) {
 75 |     if (error.message.match(/fetch/) && attempts <= 3) {
 76 |       retry()
 77 |     } else {
 78 |       fail()
 79 |     }
 80 |   }
 81 | })
 82 | ```
 83 | 
 84 | - The `delay` and `timeout` options work exactly the same as 2.x.
 85 | 
 86 | **Difference from 2.x:**
 87 | 
 88 | - The `component` option is replaced by the new `loader` option, which accepts the same loader function as in the simple usage.
 89 | 
 90 |   In 2.x, an async component with options is defined as
 91 | 
 92 |   ```ts
 93 |   () => ({
 94 |     component: Promise<Component>
 95 |     // ...other options
 96 |   })
 97 |   ```
 98 | 
 99 |   Whereas in 3.x it is now:
100 | 
101 |   ```ts
102 |   defineAsyncComponent({
103 |     loader: () => Promise<Component>
104 |     // ...other options
105 |   })
106 |   ```
107 | 
108 | - 2.x `loading` and `error` options are renamed to `loadingComponent` and `errorComponent` respectively to be more explicit.
109 | 
110 | ## Retry Control
111 | 
112 | The new `onError` option provides a hook to perform customized retry behavior in case of a loader error:
113 | 
114 | ``` js
115 | const Foo = defineAsyncComponent({
116 |   // ...
117 |   onError(error, retry, fail, attempts) {
118 |     if (error.message.match(/fetch/) && attempts <= 3) {
119 |       // retry on fetch errors, 3 max attempts
120 |       retry()
121 |     } else {
122 |       fail()
123 |     }
124 |   }
125 | })
126 | ```
127 | 
128 | Note that `retry/fail` are like `resolve/reject` of a promise: one of them must be called for the error handling to continue.
129 | 
130 | ## Using with Suspense
131 | 
132 | Async component in 3.x are *suspensible* by default. This means if it has a `<Suspense>` in the parent chain, it will be treated as an async dependency of that `<Suspense>`. In this case, the loading state will be controlled by the `<Suspense>`, and the component's own `loading`, `error`, `delay` and `timeout` options will be ignored.
133 | 
134 | The async component can opt-out of Suspense control and let the component always control its own loading state by specifying `suspensible: false` in its options.
135 | 
136 | # Adoption strategy
137 | 
138 | - The syntax conversion is mechanical and can be performed via a codemod. The challenge is in determining which plain functions should be considered async components. Some basic heuristics can be used:
139 | 
140 |   - Arrow functions that returns dynamic `import` call to `.vue` files
141 |   - Arrow functions that returns an object with the `component` property being a dynamic `import` call.
142 | 
143 |   Note this may not cover 100% of the existing usage.
144 | 
145 | - In the compat build, it is possible to check the return value of functional components and warn legacy async components usage. This should cover all Promise-based use cases.
146 | 
147 | - The only case that cannot be easily detected is 2.x async components using manual `resolve/reject` instead of returning promises. Manual upgrade will be required for such cases but they should be relatively rare.
148 | 


--------------------------------------------------------------------------------
/active-rfcs/0027-custom-elements-interop.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-03-25
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: N/A
  4 | 
  5 | # Summary
  6 | 
  7 | - **Breaking:** Custom Elements whitelisting is now performed during template compilation, and should be configured via compiler options instead of runtime config.
  8 | 
  9 | - **Breaking:** Restrict the special `is` prop usage to the reserved `<component>` tag only.
 10 | 
 11 | - Introduce a new `v-is` directive to support 2.x use cases where `is` was used on native elements to work around native HTML parsing restrictions.
 12 | 
 13 | # Motivation
 14 | 
 15 | - Provide native custom element support in a more performant fashion
 16 | - Improve support for [customized built-in elements](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-customized-builtin-example).
 17 | 
 18 | # Detailed design
 19 | 
 20 | ## Autonomous Custom Elements
 21 | 
 22 | In Vue 2.x, whitelisting tags as custom elements is done via `Vue.config.ignoredElements`. The downside is that when this config option is used, a check needs to be performed on every vnode creation call.
 23 | 
 24 | **In Vue 3.0, this check is performed during template compilation.** For example, given the following template:
 25 | 
 26 | ```html
 27 | <plastic-button></plastic-button>
 28 | ```
 29 | 
 30 | The default generated render function code is (pseudo code):
 31 | 
 32 | ```js
 33 | function render() {
 34 |   const component_plastic_button = resolveComponent('plastic-button')
 35 |   return createVNode(component_plastic_button)
 36 | }
 37 | ```
 38 | 
 39 | And it will emit a warning if no component named `plastic-button` was found.
 40 | 
 41 | If the user wishes to use a native custom element named `plastic-button`, the desired generated code should be:
 42 | 
 43 | ```js
 44 | function render() {
 45 |   return createVNode('plastic-button') // render as native element
 46 | }
 47 | ```
 48 | 
 49 | To instruct the compiler to treat `<plastic-button>` as a custom element:
 50 | 
 51 | - If using a build step: pass the `isCustomElement` option to the Vue template compiler. If using `vue-loader`, this should be passed via `vue-loader`'s `compilerOptions` option:
 52 | 
 53 |   ```js
 54 |   // in webpack config
 55 |   rules: [
 56 |     {
 57 |       test: /\.vue$/,
 58 |       use: 'vue-loader',
 59 |       options: {
 60 |         compilerOptions: {
 61 |           isCustomElement: tag => tag === 'plastic-button'
 62 |         }
 63 |       }
 64 |     }
 65 |     // ...
 66 |   ]
 67 |   ```
 68 | 
 69 | - If using on-the-fly template compilation, pass it via `app.config`:
 70 | 
 71 |   ```js
 72 |   const app = Vue.createApp(/* ... */)
 73 | 
 74 |   app.config.isCustomElement = tag => tag === 'plastic-button'
 75 |   ```
 76 | 
 77 |   Note the runtime config only affects runtime template compilation - it won't affect pre-compiled templates.
 78 | 
 79 | ## Customized Built-in Elements
 80 | 
 81 | The Custom Elements specification provides a way to use custom elements as [Customized Built-in Element](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-customized-builtin-example) by adding the `is` attribute to a built-in element:
 82 | 
 83 | ```html
 84 | <button is="plastic-button">Click Me!</button>
 85 | ```
 86 | 
 87 | Vue's usage of the `is` special prop was simulating what the native attribute does before it was made universally available in browsers. However, in 2.x it is interpreted as rendering a Vue component with the name `plastic-button`. This blocks the native usage of Customized Built-in Element mentioned above.
 88 | 
 89 | In 3.0, we are limiting Vue's special treatment of the `is` prop to the `<component>` tag only.
 90 | 
 91 | - When used on the reserved `<component>` tag, it will behave exactly the same as in 2.x.
 92 | 
 93 | - When used on normal components, it will behave like a normal prop:
 94 | 
 95 |   ```html
 96 |   <foo is="bar" />
 97 |   ```
 98 | 
 99 |   - 2.x behavior: renders the `bar` component.
100 |   - 3.x behavior: renders the `foo` component and passing the `is` prop.
101 | 
102 | - When used on plain elements, it will be passed to the `createElement` call as the `is` option, and also rendered as a native attribute. This supports the usage of customized built-in elements.
103 | 
104 |   ```html
105 |   <button is="plastic-button">Click Me!</button>
106 |   ```
107 | 
108 |   - 2.x behavior: renders the `plastic-button` component.
109 |   - 3.x behavior: renders a native button by calling
110 | 
111 |     ```js
112 |     document.createElement('button', { is: 'plastic-button' })
113 |     ```
114 | 
115 | ## `v-is` for In-DOM Template Parsing Workarounds
116 | 
117 | > Note: this section only affects cases where Vue templates are directly written in the page's HTML.
118 | 
119 | When using in-DOM templates, the template is subject to native HTML parsing rules. Some HTML elements, such as `<ul>`, `<ol>`, `<table>` and `<select>` have restrictions on what elements can appear inside them, and some elements such as `<li>`, `<tr>`, and `<option>` can only appear inside certain other elements.
120 | 
121 | In 2.x we recommended working around with these restrictions by using the `is` prop on a native tag:
122 | 
123 | ```html
124 | <table>
125 |   <tr is="blog-post-row"></tr>
126 | </table>
127 | ```
128 | 
129 | With the behavior change of `is` proposed above, we need to introduce a new directive `v-is` for working around these cases:
130 | 
131 | ```html
132 | <table>
133 |   <tr v-is="'blog-post-row'"></tr>
134 | </table>
135 | ```
136 | 
137 | Note `v-is` functions like a dynamic 2.x `:is` binding - so to render a component by its registered name, its value should be a JavaScript string literal.
138 | 
139 | # Adoption strategy
140 | 
141 | - Compat build can detect use of `config.ignoredElements` and provide appropriate warning and guidance.
142 | 
143 | - A codemod can automatically convert all 2.x non `<component>` tags with `is` usage to `<component is>` (for SFC templates) or `v-is` (for in-DOM templates).
144 | 


--------------------------------------------------------------------------------
/active-rfcs/0029-router-dynamic-routing.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-01-27
  2 | - Target Major Version: Vue 3 Router 4
  3 | - Reference Issues: [issues](https://github.com/vuejs/vue-router/issues?q=is%3Aopen+is%3Aissue+label%3A%22group%5Bdynamic+routing%5D%22)
  4 | - Implementation PR:
  5 | 
  6 | # Summary
  7 | 
  8 | Introducing an API that allows adding and removing route records while the router is working
  9 | 
 10 | - `router.addRoute(route: RouteRecord)` Add a new route
 11 | - `router.removeRoute(name: string | symbol)` Remove an existing route
 12 | - `router.hasRoute(name: string | symbol): boolean` Check if a route exists
 13 | - `router.getRoutes(): RouteRecord[]` Get the current list of routes
 14 | 
 15 | # Basic example
 16 | 
 17 | Given a router instance in a running app:
 18 | 
 19 | ```ts
 20 | router.addRoute({
 21 |   path: '/new-route',
 22 |   name: 'NewRoute',
 23 |   component: NewRoute
 24 | })
 25 | 
 26 | // add to the children of an existing route
 27 | router.addRoute('ParentRoute', {
 28 |   path: 'new-route',
 29 |   name: 'NewRoute',
 30 |   component: NewRoute
 31 | })
 32 | 
 33 | router.removeRoute('NewRoute')
 34 | 
 35 | // normalized version of the records added
 36 | const routeRecords = router.getRoutes()
 37 | ```
 38 | 
 39 | # Motivation
 40 | 
 41 | Dynamic routing is a feature that enables applications to build its own routing system. A usecase of this is the vue-cli ui, that allows adding graphical plugins which can have their own interfaces.
 42 | 
 43 | The current version of Vue Router only supports adding a new absolute route. The idea of this RFC is to add the missing functions to allow dynamic routing. Thinking about the different ways this API can be shaped and what is best for the future of Vue Router. Currently, it's impossible to achieve the example described above without hacks or creating a whole new Router instance.
 44 | 
 45 | In theory this could also improve Developer experience by changing routes in place with Hot Module Replacement.
 46 | 
 47 | Note: Dynamic routing only makes sense after implementing path ranking (automatic route order that allows route records to be added in any order but still be matched correctly). Most of the cost of adding this feature is on the path scoring side.
 48 | 
 49 | # Detailed design
 50 | 
 51 | ## `addRoute`
 52 | 
 53 | - Allow adding an absolute route
 54 | - Allow adding a child route
 55 | - How should conflicts be handled?
 56 | - What should be returned by the function?
 57 | 
 58 | The code samples are written in TS to provide more information about the shape of the object expected:
 59 | 
 60 | `RouteRecord` is the same kind of object used in the `routes` option when instantiating the Router. To give you an idea, it looks like (https://router.vuejs.org/api/#routes). Important to note, this object is consistent with the `routes` options, since the `RouteRecord` type might have minor changes in the future version of Vue Router 4.
 61 | 
 62 | ```ts
 63 | const routeRecord: RouteRecord = {
 64 |   path: '/new-route',
 65 |   name: 'NewRoute',
 66 |   component: NewRoute
 67 | }
 68 | ```
 69 | 
 70 | There are different options for what to return from `addRoute`.
 71 | 
 72 | Returning a function that allows removing the route is useful for unamed routes.
 73 | 
 74 | ```ts
 75 | const removeRoute = router.addRoute(routeRecord)
 76 | 
 77 | removeRoute() // removes the route record
 78 | // or
 79 | router.removeRoute('NewRoute') // because names are unique
 80 | ```
 81 | 
 82 | If we are on `/new-route`, adding the record will **not** trigger a _replace_ navigation. The user is responsible for forcing a navigation by calling `router.push` or `router.replace` with the current location `router.replace(router.currentRoute.value.fullPath)`. Using the string version of the location ensures that a new location is resolved instead of the old one. If the route is added inside of a navigation guard, make sure to use the value from the `to` parameter:
 83 | 
 84 | ```js
 85 | router.beforeEach((to, from, next) => {
 86 |   // ...
 87 |   router.addRoute(newRoute)
 88 |   next(to.fullPath)
 89 |   // ...
 90 | })
 91 | ```
 92 | 
 93 | Because the Dynamic Routing API is an advanced API that most users won't directly use, having this split allows more flexible and optimized behavior. The recommended approach to add routes will still be the configuration based one.
 94 | 
 95 | _For Alternatives, please check [alternatives](#alternatives)_
 96 | 
 97 | ### Conflicts
 98 | 
 99 | When adding a route that has the same name as an existing route, it should replace the existing route. This is the most convenient version, because it allows replacing new routes without having to explicitely remove the old ones **when they are using the same name**.
100 | 
101 | Alternatives:
102 | 
103 | - Fail and throw an error that asks the user to replace it first: less convenient
104 | - Not warn the user but still replace it: could be prone to difficult to debug errors
105 | 
106 | ### Nested routes
107 | 
108 | Depending on what is returned by `addRoute`, a nested route can be added by referencing the name of an existing route. This forces parent routes to be named.
109 | 
110 | ```ts
111 | router.addRoute('ParentRoute', routeRecord)
112 | ```
113 | 
114 | ### Signature
115 | 
116 | ```ts
117 | interface addRoute {
118 |   (parentName: string | symbol, route: RouteRecord): () => void
119 |   (route: RouteRecord): () => void
120 | }
121 | ```
122 | 
123 | ## `removeRoute`
124 | 
125 | Removing a route removes all its children as well. As with `addRoute`, it's necessary to trigger a new navigation in order to update the current displayed view by _RouterView_.
126 | 
127 | ```ts
128 | interface removeRoute {
129 |   (name: string | symbol): void
130 | }
131 | ```
132 | 
133 | ## `hasRoute`
134 | 
135 | Checks if a route exists:
136 | 
137 | ```ts
138 | interface hasRoute {
139 |   (name: string | symbol): boolean
140 | }
141 | ```
142 | 
143 | ## `getRoutes`
144 | 
145 | Allows reading the list of normalized route records:
146 | 
147 | ```ts
148 | interface getRoutes {
149 |   (): RouteRecordNormalized[]
150 | }
151 | ```
152 | 
153 | What is present in RouteRecordNormalized is yet to be decided, but contains at least all existing properties from a RouteRecord, some of them normalized (like `components` instead of `component` and an `undefined` name).
154 | 
155 | # Drawbacks
156 | 
157 | - This API increases vue-router size. To make it treeshakable will require allowing the matcher (responsible for parsing `path` and doing the path ranking) to be extended with simpler versions, which are quite complex to write but we could instead export different versions of the matcher and allow the user specifying the matcher in a leaner version of the router.
158 | 
159 | # Alternatives
160 | 
161 | ## `addRoutes`
162 | 
163 | - A promise that resolves or rejects based on the possible navigation that adding the record might trigger (e.g. being on `/new-route` before adding the route)
164 | 
165 | ```ts
166 | window.location.pathname // "/new-route"
167 | // 1. The promise of a function that allows removing the route record
168 | const removeRoute = await router.addRoute(routeRecord)
169 | // 2. The same kind of promise returned by `router.push`.
170 | const route = await router.addRoute(routeRecord)
171 | 
172 | removeRoute() // removes the route record
173 | // or
174 | router.removeRoute('NewRoute') // names are unique
175 | ```
176 | 
177 | - A reference to the record added (a normalized copy of the original record)
178 | 
179 | ```ts
180 | // js object (same reference hold by the router)
181 | const normalizedRouteRecord = router.addRoute(routeRecord)
182 | router.removeRoute(normalizedRouteRecord)
183 | ```
184 | 
185 | ## `getRoutes`
186 | 
187 | There could also be a reactive property with the routes, but this would allow using them in templates, which in most scenarios is an application level feature which could and should handle things the other way around, **having a reactive source of route records that are syncronized with the router**. Doing this at the application level avoids adding the cost for every user.
188 | 
189 | # Adoption strategy
190 | 
191 | - Deprecate `addRoutes` and add `addRoute` to Vue Router 3. Other methods are new.
192 | 


--------------------------------------------------------------------------------
/active-rfcs/0030-emits-option.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-02-27
  2 | - Target Major Version: 2.x & 3.x
  3 | - Reference Issues: N/A
  4 | - Implementation PR:
  5 | 
  6 | # Summary
  7 | 
  8 | Make it explicit what events are emitted by the component.
  9 | 
 10 | # Basic example
 11 | 
 12 | ```javascript
 13 | const Comp = {
 14 |   emits: {
 15 |     submit: payload => {
 16 |       // validate payload by returning a boolean
 17 |     }
 18 |   },
 19 | 
 20 |   created() {
 21 |     this.$emit('submit', {
 22 |       /* payload */
 23 |     })
 24 |   }
 25 | }
 26 | ```
 27 | 
 28 | # Motivation
 29 | 
 30 | - **Documentation:** Similar to `props`, explicit `emits` declaration serves as self-documenting code. This can be useful for other developers to instantly understand what events the component is supposed to emit.
 31 | 
 32 | - **Runtime Validation:** The option also offers a way to perform runtime validation of emitted event payloads.
 33 | 
 34 | - **Type Inference:** The `emits` option can be used to provide type inference so that `this.$emit` and `setupContext.emit` calls can be typed.
 35 | 
 36 | - **IDE Support:** IDEs can leverage the `emits` option to provide auto-completion when using `v-on` listeners on a component.
 37 | 
 38 | - **Listener Fallthrough Control:** With the proposed attribute fallthrough changes, `v-on` listeners on components will fallthrough as native listeners by default. `emits` provides a way to declare events as component-only to avoid unnecessary registration of native listeners.
 39 | 
 40 | # Detailed design
 41 | 
 42 | A new optional component option named `emits` is introduced.
 43 | 
 44 | ## Array Syntax
 45 | 
 46 | For simple use cases, the option value can be an Array containing string events names:
 47 | 
 48 | ```javascript
 49 | {
 50 |   emits: [
 51 |     'eventA',
 52 |     'eventB'
 53 |   }
 54 | }
 55 | ```
 56 | 
 57 | ## Object Syntax
 58 | 
 59 | Or it can be an object with event names as its keys. The value of each property can either be `null` or a validator function. The validation function will receive the additional arguments passed to the `$emit` call. For example, if `this.$emit('foo', 1, 2)` is called, the corresponding validator for `foo` will receive the arguments `1, 2`. The validator function should return a boolean to indicate whether the event arguments are valid.
 60 | 
 61 | ```javascript
 62 | {
 63 |   emits: {
 64 |     // no validation
 65 |     click: null,
 66 | 
 67 |     // with validation
 68 |     //
 69 |     submit: payload => {
 70 |       if (payload.email && payload.password) {
 71 |         return true
 72 |       } else {
 73 |         console.warn(`Invalid submit event payload!`)
 74 |         return false
 75 |       }
 76 |     }
 77 |   }
 78 | }
 79 | ```
 80 | 
 81 | ## Fallthrough Control
 82 | 
 83 | The new [Attribute Fallthrough Behavior](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0031-attr-fallthrough.md) proposed in [#154](https://github.com/vuejs/rfcs/pull/154) now applies automatic fallthrough for `v-on` listeners used on a component:
 84 | 
 85 | ```html
 86 | <Foo @click="onClick" />
 87 | ```
 88 | 
 89 | We are not making `emits` required for `click` to be trigger-able by component emitted events for backwards compatibility. Therefore in the above example, without the `emits` option, the listener can be triggered by both a native click event on `Foo`'s root element, or a custom `click` event emitted by `Foo`.
 90 | 
 91 | If, however, `click` is declared as a custom event by using the `emits` option, it will then only be triggered by custom events and will no longer fallthrough as a native listener.
 92 | 
 93 | Event listeners declared by `emits` are also excluded from `this.$attrs` of the component.
 94 | 
 95 | ## Type Inference
 96 | 
 97 | The Object validator syntax was picked with TypeScript type inference in mind. The validator type signature can be used to type `$emit` calls:
 98 | 
 99 | ```ts
100 | const Foo = defineComponent({
101 |   emits: {
102 |     submit: (payload: { email: string; password: string }) => {
103 |       // perform runtime validation
104 |     }
105 |   },
106 | 
107 |   methods: {
108 |     onSubmit() {
109 |       this.$emit('submit', {
110 |         email: 'foo@bar.com',
111 |         password: 123 // Type error!
112 |       })
113 | 
114 |       this.$emit('non-declared-event') // Type error!
115 |     }
116 |   }
117 | })
118 | ```
119 | 
120 | # Drawbacks
121 | 
122 | - The option requires some extra effort for all components that emit custom events. However, it is technically optional, and the benefits should outweigh the extra effort needed.
123 | 
124 | - Runtime validations should only be performed in dev mode but can potentially bloat production bundle size. Props validators have the same issue. Both can be solved with a Babel plugin that transforms `props` and `emits` options to the Array format in production builds. This way the dev only code is stripped but the runtime behavior will stay consistent.
125 | 
126 | # Adoption strategy
127 | 
128 | The introduction of the `emits` option should not break any existing usage of `$emit`.
129 | 
130 | However, with the fallthrough behavior change, it would be ideal to always declare emitted events. We can:
131 | 
132 | 1. Provide a codemod that automatically scans all instances of `$emit` calls in a component and generate the `emits` option.
133 | 
134 | 2. (Opt-in) Emit a runtime warning when an emitted event isn't explicitly declared using the option.
135 | 


--------------------------------------------------------------------------------
/active-rfcs/0031-attr-fallthrough.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2019-11-05
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: N/A
  4 | - Implementation PR: N/A
  5 | 
  6 | # Summary
  7 | 
  8 | - `v-on` listeners used on a component will fallthrough and be registered as native listeners on the child component root. `.native` modifier is no longer needed.
  9 | 
 10 | - `inheritAttrs: false` now affects `class` and `style`.
 11 | 
 12 | - `this.$attrs` now contains everything passed to the component minus those explicitly declared as props, including `class`, `style`, and `v-on` listeners. `this.$listeners` is removed.
 13 | 
 14 | - Functional components attribute fallthrough behavior adjusted:
 15 |   - With explicit `props` declaration: full fallthrough like stateful components.
 16 |   - With no `props` declaration: only fallthrough for `class`, `style` and `v-on` listeners.
 17 | 
 18 | # Motivation
 19 | 
 20 | In Vue 2.x, components have an implicit attributes fallthrough behavior. Any attribute passed to a component that is not declared as a prop by the component, is considered an **extraneous attribute**. Fore example:
 21 | 
 22 | ``` html
 23 | <MyComp id="foo"/>
 24 | ```
 25 | 
 26 | If `MyComp` didn't declare a prop named `id`, then the `id` is considered an extraneous attribute and will implicitly be applied to the root node of `MyComp`.
 27 | 
 28 | This behavior is very convenient when tweaking layout styling between parent and child (by passing on `class` and `style`), or applying a11y attributes to child components.
 29 | 
 30 | This behavior can be disabled with `inheritAttrs: false`, where the user expects to explicitly control where the attributes should be applied. These extraneous attributes are exposed in an instance property: `this.$attrs`.
 31 | 
 32 | There are a number of inconsistencies and issues in the 2.x behavior:
 33 | 
 34 | - `inheritAttrs: false` does not affect `class` and `style`.
 35 | 
 36 | - Implicit fallthrough does not apply for event listeners, leading to the need for `.native` modifier if the user wish to add a native event listener to the child component root.
 37 | 
 38 | - `class`, `style` and `v-on` listeners are not included in `$attrs`, making it cumbersome for a higher-order component (HOC) to properly pass everything down to a nested child component.
 39 | 
 40 | - Functional components have no implicit attrs fallthrough behavior.
 41 | 
 42 | In 3.x, we are also introducing Fragments (multiple root nodes in a component template), which require additional considerations on the behavior.
 43 | 
 44 | # Detailed design
 45 | 
 46 | ## `v-on` Listener Fallthrough
 47 | 
 48 | With the following usage:
 49 | 
 50 | ```html
 51 | <MyButton @click="hello" />
 52 | ```
 53 | 
 54 | - In v2, the `@click` will only register a component custom event listener. To attach a native listener to the root of `MyButton`, `@click.native` is needed.
 55 | 
 56 | - In v3, the `@click` listener will fallthrough and register a native click listener on the root of `MyButton`. This means component authors no longer need to proxy native DOM events to custom events in order to support `v-on` usage without the `.native` modifier. In fact, the `.native` modifier will be removed altogether.
 57 | 
 58 | ### Avoiding Unnecessary Native Listeners
 59 | 
 60 | The v3 behavior may result in unnecessary registration of native event listeners when the component author intends to use that event name as a component emitted custom event only.
 61 | 
 62 | With flat VNode data and the removal of `.native` modifier, all listeners are passed down to the child component as `onXXX` functions:
 63 | 
 64 | ``` html
 65 | <foo @click="foo" @custom="bar" />
 66 | ```
 67 | 
 68 | compiles to:
 69 | 
 70 | ``` js
 71 | h(foo, {
 72 |   onClick: foo,
 73 |   onCustom: bar
 74 | })
 75 | ```
 76 | 
 77 | With the fallthrough, all parent listeners are applied to the target element as native DOM listeners. In the above example, both a native click event and a custom one emitted by `this.$emit('click')` in the child will trigger the parent's `foo` handler. This may lead to unwanted behavior.
 78 | 
 79 | The introduction of the `emits` option, as proposed in [#16](https://github.com/vuejs/rfcs/pull/16), provides a way to explicit declare an event to be a component custom event so that the event's listener will be excluded from the fallthrough (and `this.$attrs` in case of manual control). The two RFCs should be considered in tandem.
 80 | 
 81 | ## Explicitly Controlling the Fallthrough
 82 | 
 83 | ### `inheritAttrs: false`
 84 | 
 85 | With `inheritAttrs: false`, the implicit fallthrough is disabled. The component can either choose to intentionally ignore all extraneous attrs, or explicitly control where the attrs should be applied via `v-bind="$attrs"`:
 86 | 
 87 | ``` html
 88 | <div class="wrapper">
 89 |   <!-- apply attrs to an inner element instead of root -->
 90 |   <input v-bind="$attrs">
 91 | </div>
 92 | ```
 93 | 
 94 | `this.$attrs` (and `context.attrs` for `setup()` and functional components) now contains all attributes passed to the component (as long as it is not declared as props). This includes `class`, `style`, normal attributes and `v-on` listeners. This is based on the flat props structure proposed in [Render Function API Change](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0008-render-function-api-change.md#flat-vnode-props-format).
 95 | 
 96 | `v-on` listeners are included in `$attrs` as `onXXX` props. For example, `@click` will result in an `onClick` prop in `$attrs`. If the user wants to handle attributes and listeners separately, it can be done with simple helper functions that separate props that start with `on` from those that don't.
 97 | 
 98 | ### Multiple Root / Fragment Components
 99 | 
100 | In Vue 3, components can have multiple root elements (i.e. fragment root). In such cases, an automatic merge cannot be performed. The user will be responsible for spreading the attrs to the desired element:
101 | 
102 | ``` html
103 | <template>
104 |   <span>hello</span>
105 |   <div v-bind="$attrs">main element</div>
106 | </template>
107 | ```
108 | 
109 | If `$attrs` is non-empty, and the user did not perform an explicit spread (checked by access to `this.$attrs` during render), a runtime warning will be emitted. The component should either bind `$attrs` to an element, or explicitly suppress the warning with `inheritAttrs: false`.
110 | 
111 | ### In Render Functions
112 | 
113 | In manual render functions, it may seem convenient to just use a spread:
114 | 
115 | ``` js
116 | export default {
117 |   props: { /* ... */ },
118 |   inheritAttrs: false,
119 |   render() {
120 |     return h('div', { class: 'foo', ...this.$attrs })
121 |   }
122 | }
123 | ```
124 | 
125 | However, this will cause attrs to overwrite whatever existing props of the same name. For example, there the local `class` may be overwritten when we probably want to merge the classes instead. Vue provides a `mergeProps` helper that handles the merging of `class`, `style` and `onXXX` listeners:
126 | 
127 | ``` js
128 | import { mergeProps } from 'vue'
129 | 
130 | export default {
131 |   props: { /* ... */ },
132 |   inheritAttrs: false,
133 |   render() {
134 |     return h('div', mergeProps({ class: 'foo' }, this.$attrs))
135 |   }
136 | }
137 | ```
138 | 
139 | This is also what `v-bind` uses internally.
140 | 
141 | If returning the render function from `setup`, the attrs object is exposed on the setup context:
142 | 
143 | ``` js
144 | import { mergeProps } from 'vue'
145 | 
146 | export default {
147 |   props: { /* ... */ },
148 |   inheritAttrs: false,
149 |   setup(props, { attrs }) {
150 |     return () => {
151 |       return h('div', mergeProps({ class: 'foo' }, attrs))
152 |     }
153 |   }
154 | }
155 | ```
156 | 
157 | Note the `attrs` object is updated before every render, so it's ok to destructure it.
158 | 
159 | ## Functional Components
160 | 
161 | In 2.x, functional components do not support automatic attribute fallthrough and require manual props merging.
162 | 
163 | In v3, functional components use a different syntax: they are now declared as plain functions (as specified in [Render Function API Change](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0008-render-function-api-change.md#functional-component-signature)).
164 | 
165 | ### With Explicit Props Declaration
166 | 
167 | A functional component with `props` declaration will have the same automatic fallthrough behavior as stateful components. It can also explicitly control the attrs with `inheritAttrs: false`:
168 | 
169 | ``` js
170 | const Func = (props, { attrs }) => {
171 |   return h('div', mergeProps({ class: 'foo' }, attrs), 'hello')
172 | }
173 | 
174 | Func.props = { /*...*/ }
175 | Func.inheritAttrs = false
176 | ```
177 | 
178 | ### With Optional Props Declaration
179 | 
180 | v3 functional components also support [Optional Props Declaration](#TODO). When a functional component has no `props` option defined, it receives all attributes passed by the parent as its `props`:
181 | 
182 | ``` js
183 | const Foo = props => h('div', { class: 'foo' }, props.msg)
184 | ```
185 | 
186 | When a functional component is leveraging optional props declaration, there is only implicit fallthrough for `class`, `style`, and `v-on` listeners.
187 | 
188 | The reason for `class`, `style` and `v-on` listeners to be whitelisted is because:
189 | 
190 | - They cover the most common use cases for attribute fallthrough.
191 | - They have close to no risk of clashing with prop names.
192 | - They require special merge logic instead of simple overwrites, so handling them implicitly yields more convenience value.
193 | 
194 | If a functional component with optional props declaration needs to support full attribute fallthrough, it needs to declare `inheritAttrs: false`, pick the desired attrs from `props`, and merge it to the root element:
195 | 
196 | ``` js
197 | // destructure props, and use rest spread to grab unused ones as attrs.
198 | const Func = ({ msg, ...attrs }) => {
199 |   return h('div', mergeProps({ class: 'foo' }, attrs), msg)
200 | }
201 | Func.inheritAttrs = false
202 | ```
203 | 
204 | ## API Deprecations
205 | 
206 | - `.native` modifier for v-on will be removed.
207 | - `this.$listeners` will be removed.
208 | 
209 | # Adoption strategy
210 | 
211 | - Deprecations can be supported in the compat build:
212 |   - `.native` modifier will be a no-op and emit a warning during template compilation.
213 |   - `this.$listeners` can be supported with a runtime warning.
214 | 
215 | - There could technically be cases where the user relies on the 2.x behavior where `inheritAttrs: false` does not affect `class` and `style`, but it should be very rare. We will have a dedicated item in the migration guide / helper to remind the developer to check for such cases.
216 | 
217 | - Since functional components uses a new syntax, they will likely require manual upgrades. We should have a dedicated section for functional components in the migration guide.
218 | 


--------------------------------------------------------------------------------
/active-rfcs/0032-vtu-improve-async-workflow.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020.02.01
  2 | - Target Major Version: VTU beta-0.3x/1.x
  3 | - Reference Issues:
  4 | - Implementation PR:
  5 | 
  6 | # Summary
  7 | 
  8 | Allows the Vue Test Utils APIs that trigger re-renders to be awaited. This makes asserting changes after re-renders easier.
  9 | 
 10 | # Basic example
 11 | ```js
 12 |     const wrapper = mount(Component)
 13 |     await wrapper.find('.element').trigger('click')
 14 |     expect(wrapper.emitted('event')).toBeTruthy()
 15 | ```
 16 | # Motivation
 17 | 
 18 | With the removal of `sync` mode in Vue Test Utils `beta-29`, we now need to `await` for things like watchers or the template to re-render, before we make assertions.
 19 | 
 20 | This proposal aims to make it easier for developers to work with async tests, by allowing you to  `await` calls like `trigger` or those that use it internally. 
 21 | 
 22 | The proposal assumes the usage of `async/await` inside tests.
 23 | 
 24 | # Detailed design
 25 | 
 26 | The general idea is to return a promise resolving on `nextTick`, from actions that trigger async changes. 
 27 | 
 28 | At this moment we need to manually `await` for the component to update. This leads to extra boilerplate, and is harder to grasp for beginners.
 29 | 
 30 | ```js
 31 |     const wrapper = mount(Component)
 32 |     wrapper.find('.element').trigger('click')
 33 |     // we need to wait for the component to render
 34 |     await wrapper.vm.$nextTick()
 35 |     expect(wrapper.emitted('event')).toBeTruthy()
 36 | ```
 37 | 
 38 | The new API should look like:
 39 | 
 40 | ```js
 41 |     const wrapper = mount(Component)
 42 |     await wrapper.find('.element').trigger('click')
 43 |     expect(wrapper.emitted('event')).toBeTruthy()
 44 | ```
 45 | 
 46 | With more complicated tests, the benefits are obvious:
 47 | 
 48 | ```js
 49 |     await wrapper.find('.button').trigger('click')
 50 |     expect(wrapper.emitted('event')).toBeTruthy()
 51 |     
 52 |     await wrapper.find('.country-option').setValue('US')
 53 |     expect(wrapper.find('.state').exists()).toBe(true)
 54 |     
 55 |     await wrapper.find('.radio-option').setChecked()
 56 |     expect(wrapper.find('.finish').attributes('disabled')).toBeFalsy()  
 57 | ```
 58 | 
 59 | **Methods that should return a promise, resolving on next tick:**
 60 | 
 61 | - trigger
 62 | - setValue
 63 | - setChecked
 64 | - setData
 65 | - setProps
 66 | - setSelected
 67 | - setValue
 68 | 
 69 | Most of the above helpers rely on trigger internally, so updating the majority of listed methods would be easy.
 70 | 
 71 | ### Additional helpers
 72 | 
 73 | Currently we have seen 3 ways to await for changes:
 74 | 
 75 | ```js
 76 |     import flushPromises from 'flush-promises'
 77 |     await flushPromises()
 78 |     // or the more preferred
 79 |     await wrapper.vm.$nextTick()
 80 |     await Vue.nextTick()
 81 | ```
 82 | 
 83 | In Vue 3 `nextTick` will be removed from the VM instance, so users will have to migrate over to importing it from Vue directly `import { nextTick } from 'vue'`. 
 84 | 
 85 | A `tick` helper can be added to the VTU exports. That way users have everything in one place, and an official way to await for renders, from actions that cannot directly return a promise.
 86 | 
 87 | Such a case is triggering a custom Vue event.
 88 | 
 89 | ```js
 90 |     import { mount, tick } from '@vue/test-utils'
 91 |     
 92 |     it('test' => {
 93 |     	const wrapper = mount(Component)
 94 |      	wrapper.find('.input').vm.$emit('input', 'Newly added note')	
 95 |     	await tick()
 96 |     
 97 |     	expect(wrapper).toMatchSnapshot()
 98 |     })
 99 | ```
100 | 
101 | Or we could be focusing an element on mounted, which is usually done on next tick
102 | 
103 | ```js
104 |     const wrapper = mount(Component)
105 |     // await data to be focused on mounted
106 |     await tick()
107 |     let input = wrapper.find('input').element
108 |     expect(input).toBe(document.activeElement)
109 | ```
110 | 
111 | # Drawbacks
112 | 
113 | Each `trigger` will now call `nextTick()` , which I am not sure if it can hurt performance.
114 | 
115 | Users may try to `await` anything that interacts with the DOM, so it is a matter of writing good DOCs and guides on the topic.
116 | 
117 | # Alternatives
118 | 
119 | # Adoption strategy
120 | 
121 | ### Vue Test Utils beta-30+
122 | 
123 | Users would have to make sure `async/await` is working in their testing env.
124 | 
125 | Users just have to remove extra `$nextTick` and `flushPromises` calls and use the new api.
126 | 
127 | Improve docs on the topic.
128 | 
129 | ### Vue Test Utils prior to beta-30
130 | 
131 | Before the removal of `sync` mode it was not necessary to await for renders.
132 | 
133 | # Unresolved questions
134 | 


--------------------------------------------------------------------------------
/active-rfcs/0033-router-navigation-failures.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-03-26
  2 | - Target Major Version: Vue Router v4
  3 | - Reference Issues: https://github.com/vuejs/vue-router/issues/2833, https://github.com/vuejs/vue-router/pull/3047, https://github.com/vuejs/vue-router/issues/2932, https://github.com/vuejs/vue-router/issues/2881
  4 | - Implementation PR:
  5 | 
  6 | # Summary
  7 | 
  8 | - Explicitly define what a navigation failure is, and how and where we can catch them.
  9 | - Change when the Promised-based `router.push`(and `router.replace` by extension) resolves and rejects.
 10 | - Make `router.push` consistent with `router.afterEach` and `router.onError`.
 11 | 
 12 | # Basic example
 13 | 
 14 | ## `router.push`
 15 | 
 16 | If there is an unhandled error or an error is passed to `next`:
 17 | 
 18 | ```js
 19 | // any other navigation guard
 20 | router.beforeEach((to, from, next) => {
 21 |   next(new Error())
 22 |   // or
 23 |   throw new Error()
 24 |   // or
 25 |   return Promise.reject(new Error())
 26 | })
 27 | ```
 28 | 
 29 | Then the promise returned by `router.push` rejects:
 30 | 
 31 | ```js
 32 | router.push('/url').catch((err) => {
 33 |   // ...
 34 | })
 35 | ```
 36 | 
 37 | In **all** other cases, the promise is resolved. We can know if the navigation failed or not by checking the resolved value:
 38 | 
 39 | ```js
 40 | router.push('/dashboard').then((failure) => {
 41 |   if (failure) {
 42 |     failure instanceof Error // true
 43 |     failure.type // NavigationFailure.canceled
 44 |   }
 45 | })
 46 | ```
 47 | 
 48 | ## `router.afterEach`
 49 | 
 50 | It's the global equivalent of `router.push().then()`
 51 | 
 52 | ## `router.onError`
 53 | 
 54 | It's the global equivalent of `router.push().catch()`
 55 | 
 56 | # Motivation
 57 | 
 58 | The current behavior of Vue Router regarding the promise returned by `push` is inconsistent with `router.afterEach` and `router.onError`. Ideally, we should be able to catch all succeeded and failed navigations globally and locally but we can only do it locally.
 59 | 
 60 | - `onError` is only triggered on thrown errors and `next(new Error())`
 61 | - `afterEach` is only called if there is a navigation
 62 | - `redirect` should behave the same as `next('/url')` in a Navigation guard when it comes to the outcome of `router.push` and calls of `router.afterEach`/`router.onError`. The only difference being that a `redirect` would only trigger leave guards and other before guards for the redirected location but not the original one
 63 | 
 64 | The differences between the Promise resolution/rejection vs `router.afterEach` and `router.onError` are inconsistent and confusing.
 65 | 
 66 | # Detailed design
 67 | 
 68 | One of the main points is to be able to consistently handle failed navigations globally and locally:
 69 | 
 70 | - Failed Navigation:
 71 |   - Triggers `router.afterEach`
 72 |   - Resolves the `Promise` returned by `router.push`
 73 | - Uncaught Errors, `next(new Error())`
 74 |   - Triggers `router.onError`
 75 |   - Rejects the `Promise` returned by `router.push`
 76 | 
 77 | It's important to note there is no overlap in these two groups: if there is an unhandled error in a Navigation Guard, it will trigger `router.onError` as well as rejecting the `Promise` returned by `router.push` but **will not trigger** `router.afterEach`. Cancelling a navigation with `next(false)` will not trigger `router.onError` but will trigger `router.afterEach`
 78 | 
 79 | ## Changes to the Promise resolution and rejection
 80 | 
 81 | Navigation methods like `push` return a Promise, this promise **resolves** once the navigation succeeds **or** fail. It **rejects** only if there was an unhandled error. If it rejects, it will also trigger `router.onError`.
 82 | 
 83 | To differentiate a Navigation that succeeded from one that failed, the `Promise` returned by `push` will resolve to either `undefined` or a `NavigationFailure`:
 84 | 
 85 | ```js
 86 | import { NavigationFailureType, isNavigationFailure } from 'vue-router'
 87 | 
 88 | router.push('/').then((failure) => {
 89 |   if (failure) {
 90 |     // Having an Error instance allows us to have a Stacktrace and trace back
 91 |     // where the navigation was cancelled. This will, in many cases, lead to a
 92 |     // Navigation Guard and the corresponding `next()` call that cancelled the
 93 |     // navigation
 94 |     failure instanceof Error // true
 95 |     if (isNavigationFailure(failure, NavigationFailureType.canceled)) {
 96 |       // ...
 97 |     }
 98 |   }
 99 | })
100 | 
101 | // using async/await
102 | let failure = await router.push('/')
103 | if (failure) {
104 |   // ...
105 | }
106 | ```
107 | 
108 | By not rejecting the `Promise` when the navigation fails, we are avoiding _Uncaught (in promise)_ errors while still keeping the possibility to check if the Navigation failed or not.
109 | 
110 | ### Navigation Failures
111 | 
112 | There are a few different navigation failures, to be able to react differently in your code
113 | 
114 | Navigation failures can be differentiated through a `type` property **although you don't need to directly check it**. All possible values are hold by an `enum`, `NavigationFailureType`:
115 | 
116 | - `aborted`: a newer navigation took place while the current one was ongoing.
117 | - `cancelled`: `next(false)` inside of a navigation guard.
118 | - `duplicated`: Navigating to the same location as the current one will cancel the navigation and not invoke any Navigation guard.
119 | 
120 | On top of the `type` property, navigation failures also expose `from` and `to` properties, exactly like `router.afterEach`
121 | 
122 | ### Redirections
123 | 
124 | Redirecting inside of a navigation guard with `next('/url')` is not a navigation failure by itself, as the navigation still takes place and ends up somewhere. To detect a navigation, specially during SSR, there is a `redirectedFrom` property accessible on the `currentRoute`.
125 | 
126 | E.g.: imagine a navigation guard that redirects to `/login` when the user isn't authenticated:
127 | 
128 | ```js
129 | router.beforeEach((to, from, next) => {
130 |   // redirect to the login page if the target location requires authentication
131 |   if (to.meta.requiresAuth && !isAuthenticated) next('/login')
132 |   else next()
133 | })
134 | ```
135 | 
136 | When navigating to a location that requires authentication, we can retrieve the original location the user was trying to access via `redirectedFrom`:
137 | 
138 | ```js
139 | // user is not authenticated
140 | await router.push('/profile/dashboard')
141 | 
142 | // `redirectedFrom` is a RouteLocationNormalized, like `currentRoute` but we are omitting
143 | // most properties to make the example readable
144 | router.currentRoute // { path: '/login', redirectedFrom: { path: '/profile/dashboard' } }
145 | ```
146 | 
147 | ## Changes to `router.afterEach`
148 | 
149 | Since `router.afterEach` also triggers when a navigation fails, we need a way to know if the navigation succeeded or failed. To do that, we introduce an extra parameter that contains the same _failure_ we could find in a resolved navigation:
150 | 
151 | ```js
152 | import { NavigationFailureType, isNavigationFailure } from 'vue-router'
153 | 
154 | router.afterEach((to, from, failure) => {
155 |   if (isNavigationFailure(failure)) {
156 |     // ...
157 |   }
158 | })
159 | ```
160 | 
161 | ## Differentiating Navigation failures
162 | 
163 | Instead of directly checking the `type` property, we can use the `isNavigationFailure` helper:
164 | 
165 | ```js
166 | import { NavigationFailureType, isNavigationFailure } from 'vue-router'
167 | 
168 | router.afterEach((to, from, failure) => {
169 |   // Any kind of navigation failure
170 |   if (isNavigationFailure(failure)) {
171 |     // ...
172 |   }
173 |   // Only duplicated navigations
174 |   if (isNavigationFailure(failure, NavigationFailureType.duplicated)) {
175 |     // ...
176 |   }
177 |   // Aborted or canceled navigations
178 |   if (
179 |     isNavigationFailure(
180 |       failure,
181 |       NavigationFailureType.aborted | NavigationFailureType.canceled
182 |     )
183 |   ) {
184 |     // ...
185 |   }
186 | })
187 | ```
188 | 
189 | # Drawbacks
190 | 
191 | - Breaking change although migration is relatively simple and in many cases will allow the developer to remove existing code
192 | 
193 | # Adoption strategy
194 | 
195 | - Expose `NavigationFailureType` and `isNavigationFailure` in vue-router@3 so that Navigation Failures can be told apart from regular Errors.
196 | - `afterEach` and `onError` are relatively simple to migrate, most of the time they are not used many times either.
197 | - `router.push` doesn't reject when navigation fails anymore. Any code relying on catching an error should await the promise result instead.
198 | 


--------------------------------------------------------------------------------
/active-rfcs/0034-router-view-keep-alive-transitions.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2020-04-20
 2 | - Target Major Version: Vue Router 4.x
 3 | - Reference Issues:
 4 | - Implementation PR:
 5 | 
 6 | # Summary
 7 | 
 8 | Given the changes to functional components in Vue 3, `KeepAlive` and `Transition` usage combined with `RouterView` is no longer possible by simply wrapping `RouterView` with `KeepAlive`/`Transition`. Instead we need a way to directly provide the component rendered by `RouterView` to those components:
 9 | 
10 | ```vue
11 | <router-view v-slot="{ Component }">
12 |   <transition :name="transitionName" mode="out-in">
13 |     <component :is="Component"></component>
14 |   </transition>
15 | </router-view>
16 | ```
17 | 
18 | # Motivation
19 | 
20 | As described at https://github.com/vuejs/vue-next/issues/906#issuecomment-611080663, we need a new API to allow the usage of `KeepAlive` and other components accepting slots with `RouterView`. In order to implement such behavior we need to be able to **directly** wrap the component rendered by `RouterView`. The only way to do so by having access to the component rendered by `RouterView` and the _props_ passed to it.
21 | 
22 | # Detailed design
23 | 
24 | We can achieve this level of control through a slot:
25 | 
26 | ```vue
27 | <router-view v-slot="{ Component, route }">
28 |   <component :is="Component" v-bind="route.params"></component>
29 | </router-view>
30 | ```
31 | 
32 | In the example, `Component` is the _component definition_ that can be passed to the function `h` or to the `is` prop of `component`.
33 | 
34 | When defining a `props: true` option in the route definition:
35 | 
36 | ```js
37 | createRouter({
38 |   routes: [{ path: '/users/:id', component: User, props: true }],
39 | })
40 | ```
41 | 
42 | The `router-view` will automatically add the `id` prop to the rendered component with the value of the param named `id`. Note you can also do `v-bind="route.params"` like shown in the example above **instead** of using `props: true`.
43 | 
44 | ## No match case
45 | 
46 | When the current location isn't matched by any record registered by the Router, the `matched` array of a `RouteLocation` is empty and, by default, when no _slot_ is provided, it renders nothing. When we provide a _slot_, we can decide of what to display, whether we want to display a _not found_ page or we want the default behavior, we are able to do it. `Component` will be falsy if there is no component to render:
47 | 
48 | ```vue
49 | <router-view v-slot="{ Component, route }">
50 |   <component v-if="route.matched.length > 0" :is="Component"/>
51 |   <div v-else>Not Found</div>
52 | </router-view>
53 | ```
54 | 
55 | Note that this behavior is redundant with the _catch all_ route (`path: '/:pathMatch(.*)`) when it comes to displaying a not found page.
56 | 
57 | ## `v-slot` properties
58 | 
59 | - `Component`: _Component_ that can be passed to the function `h` or to the `is` prop of `component`.
60 | - `route`: Normalized Route location rendered by `RouterView`. Same as `$route` but allows easy and typed access in JSX.
61 | 
62 | ## Wrapping `RouterView` with `Transition` or `KeepAlive`
63 | 
64 | If the user accidentally wraps `RouterView` with `Transition` or is migrating their application to Vue 3, we could issue a warning pointing to the documentation (this RFC in the meantime) and hinting them to use the `v-slot` api.
65 | 
66 | ## Using both `KeepAlive` and `Transition` at the same time
67 | 
68 | When using `KeepAlive` and `Transition` at the same time, we need to do `Transition` then `KeepAlive`:
69 | 
70 | ```vue
71 | <router-view v-slot="{ Component }">
72 |   <transition name="fade" mode="out-in">
73 |     <keep-alive>
74 |       <component :is="Component"></component>
75 |     </keep-alive>
76 |   </transition>
77 | </router-view>
78 | ```
79 | 
80 | <!-- # Drawbacks -->
81 | 
82 | # Alternatives
83 | 
84 | - Using a function like `useView` that would return `Component` and `attrs` removing the use of `v-slot`.
85 | 
86 | # Adoption strategy
87 | 
88 | - A codemod could rewrite v3 to v4.
89 | 


--------------------------------------------------------------------------------
/active-rfcs/0035-router-scroll-position.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-05-31
  2 | - Target Major Version: Vue Router v3 and v4
  3 | - Reference Issues: https://github.com/vuejs/vue-router/issues/3008,
  4 | - Implementation PR: (leave this empty)
  5 | 
  6 | # Summary
  7 | 
  8 | Deprecate `selector`, `x`, `y` and `offset` and introduce instead `el`, `top`, `left` (and `behavior`) that align with native apis and are more flexible.
  9 | 
 10 | # Basic example
 11 | 
 12 | ```js
 13 | const router = new Router({
 14 |   scrollBehavior(to, from, savedPosition) {
 15 | 
 16 |     // scroll to id `can~contain-special>characters` + 200px
 17 |     return {
 18 |       el: '#can~contain-special>characters'
 19 |       // top relative offset
 20 |       top: 200
 21 |       // instead of `offset: { y: 200 }`
 22 |     }
 23 |   }
 24 | })
 25 | ```
 26 | 
 27 | Other possible values returned by `scrollBehavior`:
 28 | 
 29 | ```js
 30 | // scroll smoothly (when supported by the browser) to 400px from top and 20px from left
 31 | {
 32 |   top: 400,
 33 |   left: 20,
 34 |   behavior: 'smooth'
 35 | }
 36 | 
 37 | // scroll smoothly to selector .container
 38 | {
 39 |   el: '.container'
 40 |   behavior: 'smooth'
 41 | }
 42 | 
 43 | // directly pass an Element to `el`
 44 | {
 45 |   // use the fragment(to.hash) on the url but scroll to a child of it with a class `container`
 46 |   el: document.getElementById(to.hash.slice(1)).querySelector('.container')
 47 | }
 48 | ```
 49 | 
 50 | # Motivation
 51 | 
 52 | ## Deprecating `selector`
 53 | 
 54 | The existing scroll behavior accepts a `selector` property that internally uses `document.querySelector`. In vue-router@3 we currently have a workaround for selectors that match `/^#\d/` (id CSS selector starting with a number). This is because such selector is invalid, so we detect that and use `document.getElementById` instead. However, this breaks when using CSS combinators like `#1one .container` (select an element with class `.container` inside of an element with id `1one`). The truth is there ary many [others characters that need to be escaped](https://mathiasbynens.be/notes/css-escapes) and that we cannot escape everything, creating cases where the scroll behavior is harder to use. On top of that, it can be confusing for the user when vue-router throws because `document.querySelector` failed.
 55 | 
 56 | ## Deprecating `x`, `y` and `offset`
 57 | 
 58 | Currently there are two ways of specifying an offset and both use an `x`/`y` coordinate system that differs from native functions: native browser functions allow the use of a [`ScrollToOptions`](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions) in `scrollTo` methods. This object contains `top`, `left` and `behavior` properties.
 59 | 
 60 | # Detailed design
 61 | 
 62 | Even though it is not commented anywhere in the RFC, **`scrollBehavior` can still return a Promise of any of the mentioned types**. It is omitted to focus on the shape of the return type instead of it being able to _await_ inside of `scrollBehavior`.
 63 | 
 64 | ## Deprecating `x` and `y`
 65 | 
 66 | This aligns with [`Element.scrollTo`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo) and makes it more natural passing extra options like [`behavior`](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions/behavior).
 67 | 
 68 | ```js
 69 | { x: 0, y: 200 }
 70 | // becomes
 71 | { left: 0, top: 200 }
 72 | // it can accept `behavior`
 73 | { left: 0, top: 200, behavior: 'smooth' }
 74 | ```
 75 | 
 76 | ## Deprecating `offset`
 77 | 
 78 | Instead of taking an `offset` option alongside `selector`, we could directly accept `x` and `y` alongside `selector` when specifying an offset:
 79 | 
 80 | ```js
 81 | {
 82 |   selector: '#getting-started',
 83 |   y: -120,
 84 | }
 85 | ```
 86 | 
 87 | Which, following the proposed rename, would become
 88 | 
 89 | ```js
 90 | {
 91 |   el: '#getting-started',
 92 |   top: -120,
 93 | }
 94 | ```
 95 | 
 96 | Omitting `el` will create an absolute offset as if we were providing `x` and/or `y` in vue-router@3.
 97 | 
 98 | This also aligns with `new Vue`'s `el` option
 99 | 
100 | ## More intuitive selectors thanks to `el`
101 | 
102 | The goal of a new `el` property, would be to provide simple, _"it just works"_, selectors for most common use cases while still allowing advanced cases:
103 | 
104 | - `to.hash` refers to an _id_ on the page and is directly provided to `el`. e.g. `el: to.hash` when `to.hash` equals `#about`, `#getting-started`, or `#symbols~work`
105 | - `el` is provided a more generic selector, not necessarily coming from `to.hash`. e.g. `.container > main`, **anything not starting with `#`**
106 | - `el` is provided an `Element` to allow any advanced use case e.g. when `to.hash` starts with `#` but contains a CSS selector rather than an id: `document.querySelector(to.hash)`
107 | 
108 | Thanks to allowing a raw Element, this covers all possible cases and makes it easier to provide the user with feedback when things do not work.
109 | 
110 | ## Developer experience through warnings
111 | 
112 | Another important part of this change is warning in development when vue-router fails to find an element or when `document.querySelector` throws an Error. We can divide this in two cases:
113 | 
114 | ### `el` starts with `#`
115 | 
116 | When `el` starts with `#`, we internally use `document.getElementById(el.slice(1))`. If it doesn't find an element, **in development** mode we try using `document.querySelector`, if we find something, we tell the user to use `el: document.querySelector(${providedEl})` and explain why. If we find nothing, show the usual warning of no element was found
117 | 
118 | ### `el` doesn't start with `#`
119 | 
120 | In development mode, _try catch_ to provide an error message pointing to this great article https://mathiasbynens.be/notes/css-escapes and to [`CSS.escape`](https://developer.mozilla.org/en-US/docs/Web/API/CSS/escape) if `document.querySelector` throws. If nothing is found, display the same warning of no element was found.
121 | 
122 | # Drawbacks
123 | 
124 | - Breaking change but can be introduced through a deprecation
125 | 
126 | # Adoption strategy
127 | 
128 | - Deprecate `selector`, `x`, `y` and `offset` with a warning in v3
129 | - Remove in v4
130 | 
131 | # Notes
132 | 
133 | - This RFC does not concern scrolling to a different element than window or scrolling multiple elements at once
134 | 


--------------------------------------------------------------------------------
/active-rfcs/0036-router-view-route-prop.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2020-04-01
 2 | - Target Major Version: Vue Router v3 and v4
 3 | - Reference Issues:
 4 | - Implementation PR:
 5 | 
 6 | # Summary
 7 | 
 8 | Add a `route` prop that allows customizing what is displayed by the `router-view` component. This allows users to display a view that is not the one connected to the URL. It enables patterns like modals (https://github.com/vuejs/vue-router/issues/703#issuecomment-428123334)
 9 | 
10 | # Basic example
11 | 
12 | Imagine a `backgroundView` variable that allows us to know if we are displaying a different route. We could then compute a route location that would resolve to a different location than the one displayed on the url:
13 | 
14 | ```js
15 | const App = {
16 |   computed: {
17 |     routeWithModal() {
18 |       if (backgroundView) {
19 |         return this.$router.resolve(backgroundView)
20 |       } else {
21 |         return this.$route
22 |       }
23 |     }
24 |   }
25 | }
26 | ```
27 | 
28 | We could pass that variable to `router-view`:
29 | 
30 | ```vue
31 | <router-view :route="routeWithModal"></router-view>
32 | ```
33 | 
34 | This will in most scenarios display the component associated with the current url (`this.$route`), and in others display something different while still exposing the resolved location at `this.$route`.
35 | 
36 | # Motivation
37 | 
38 | By design, Vue Router associates a URL with a Component. This is sometimes a limitation, like with modals, and this allows escaping the limitation. It's very hard to implement a userland solution without hacks (like modifying `this.$route` at [this example](https://github.com/tmiame/vue-router-twitter-style-modals)) because it involves changing the current location. Exposing a way to modify what is displayed by `router-view` is straightforward from an implementation point of view.
39 | 
40 | # Detailed design
41 | 
42 | Vue Router already exposes the mechanism to resolve a location so users can use some global state (ideally it should be held in `window.history.state` so it is restored when navigating using the browser back and forward buttons) to generate a resolved location that can be consumed by `router-view`.
43 | 
44 | Internally, `router-view` must make sure its children (nested views) use that same location to be consistent. In v4, using `inject`/`provide` should make this simple, in v3, we might need to look up like we do for _depth_. If a `route` prop is provided, it takes precedence against any _providen_ route on the `router-view` receiving the prop **and all its children**.
45 | 
46 | The end user API is one single prop:
47 | 
48 | ```vue
49 | <router-view :route="routeWithModal"></router-view>
50 | ```
51 | 
52 | # Drawbacks
53 | 
54 | - For this mechanism to work with _Lazy Loading_, it requires for the resolved route to have been navigated to before. This ensures any lazy view has been already fetched and catched. In the scenario of modals, this is automatic because we are already on the view we want to make `router-view` display. I think this limitation makes sense because I cannot think of other use cases apart from _Modals_ when it comes to displaying a view that is not associated to the URL.
55 | 
56 | # Alternatives
57 | 
58 | - A composition function `useView` that returns a reactive component to be used with `<component :is="resultOfUseView"/>`. This solutions is way more complicated than a prop.
59 | 


--------------------------------------------------------------------------------
/active-rfcs/0037-router-return-guards.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-06-08
  2 | - Target Major Version: Vue Router 3 and 4
  3 | - Reference Issues: https://github.com/vuejs/rfcs/issues/177
  4 | - Implementation PR: https://github.com/vuejs/vue-router-next/pull/343
  5 | 
  6 | # Summary
  7 | 
  8 | Allow navigation guards to return the value **or a Promise** of it instead of calling `next`:
  9 | 
 10 | ```js
 11 | // change
 12 | router.beforeEach((to, from, next) => {
 13 |   if (!isAuthenticated) next(false)
 14 |   else next()
 15 | })
 16 | 
 17 | // into
 18 | router.beforeEach(() => isAuthenticated)
 19 | ```
 20 | 
 21 | Since we can check the amount or arguments the navigation guard has, we can automatically know if we should look at the returned value or not. **This is not a breaking change**.
 22 | 
 23 | # Motivation
 24 | 
 25 | - Avoid forgetting to call `next`
 26 | - Avoid the problem of calling `next` multiple times (since we can only return once)
 27 | - `return` is more idiomatic since it can only be called once
 28 | - Avoid the need of 3 arguments in the function if they are not all used
 29 | 
 30 | # Detailed design
 31 | 
 32 | If 2 arguments are passed to a navigation guard, Vue Router will look at the returned value as if it was passed to `next`.
 33 | 
 34 | ## Validate/cancel a navigation
 35 | 
 36 | To validate a navigation, you currently have to call `next()` or `next(true)`. Instead, you can not return anything (same as explicitly returning `undefined`) or return `true`. To cancel the navigation you could call `next(false)`, now you can explicitly `return false`:
 37 | 
 38 | ```js
 39 | router.beforeEach((to) => {
 40 |   if (to.meta.requiresAuth && !isAuthenticated) return false
 41 | })
 42 | 
 43 | // with async / await
 44 | router.beforeEach(async (to) => {
 45 |   return await canAccessPage(to)
 46 | })
 47 | ```
 48 | 
 49 | ## Redirect to a different location
 50 | 
 51 | We can redirect to a location by returning the same kind of object passed to `router.push`:
 52 | 
 53 | ```js
 54 | router.beforeEach((to) => {
 55 |   if (to.meta.requiresAuth && !isAuthenticated)
 56 |     return {
 57 |       name: 'Login',
 58 |       query: {
 59 |         redirectTo: to.fullPath,
 60 |       },
 61 |     }
 62 | })
 63 | 
 64 | // with async / await
 65 | router.beforeEach(async (to) => {
 66 |   if (!(await canAccessPage(to))) {
 67 |     return {
 68 |       name: 'Login',
 69 |       query: {
 70 |         redirectTo: to.fullPath,
 71 |       },
 72 |     }
 73 |   }
 74 | })
 75 | ```
 76 | 
 77 | ## Errors
 78 | 
 79 | Unexpected errors can still be thrown synchronously or asynchronously:
 80 | 
 81 | ```js
 82 | router.beforeEach((to) => {
 83 |   throw new Error()
 84 | })
 85 | 
 86 | // with async / await
 87 | router.beforeEach(async (to) => {
 88 |   throw new Error()
 89 | })
 90 | 
 91 | // with promises
 92 | router.beforeEach((to) => {
 93 |   return Promise.reject(new Error())
 94 | })
 95 | ```
 96 | 
 97 | # Drawbacks
 98 | 
 99 | - Vue Router 3 might preset a higher implementation cost
100 | 
101 | # Alternatives
102 | 
103 | - This could be implemented with a function helper but the idea is to shift the way we write navigation guards.
104 | 
105 | What other designs have been considered? What is the impact of not doing this?
106 | 
107 | # Adoption strategy
108 | 
109 | - Add both syntaxes to Vue Router 4 (https://github.com/vuejs/vue-router-next/pull/343/files)
110 | - A codemod should be able to handle the conversion even though it's not a breaking change
111 | 


--------------------------------------------------------------------------------
/active-rfcs/0038-vue3-ie11-support.md:
--------------------------------------------------------------------------------
 1 | - Start Date: 2021-04-02
 2 | - Target Major Version: 3.x
 3 | - Reference Issues: N/A
 4 | - Implementation PR: N/A
 5 | 
 6 | # Summary
 7 | 
 8 | - Drop IE11 support plan for Vue 3.
 9 | - Focus on backport compatible features back to Vue 2.7.
10 | 
11 | # Motivation
12 | 
13 | We have been asked about IE11 support since the start of Vue 3's development, tracing back to end of 2018. Many users have asked whether Vue 3 will support IE11, and our original plan was to release Vue 3 and let it stabilize first, and add IE11 support at a later stage. During the long development process, we've also made research and experiments for IE11 compatibility on the side, but due to the complexity involved and amount of other work at hand, it's been de-prioritized down the road.
14 | 
15 | When we take another look at the problem today in 2021, the browser and JavaScript landscape has changed quite a bit. More developers are now using modern language features, and more importantly [Microsoft itself has started to actively push users away from IE](https://techcommunity.microsoft.com/t5/windows-it-pro-blog/the-perils-of-using-internet-explorer-as-your-default-browser/ba-p/331732) with its investment in Edge. It is also [dropping IE11 support in its own major projects like Microsoft 365](https://techcommunity.microsoft.com/t5/microsoft-365-blog/microsoft-365-apps-say-farewell-to-internet-explorer-11-and/ba-p/1591666). Just a few days ago [WordPress also made the decision to drop IE11 support](https://make.wordpress.org/core/2021/03/25/discussion-summary-dropping-support-for-ie11/). IE11's global usage has [dropped below 1%](https://caniuse.com/usage-table). When we are talking about public-facing websites and apps, IE11 is on a clear fast decline.
16 | 
17 | We believe this is an opportunity to rethink IE11 support for Vue 3.
18 | 
19 | ## The cost of supporting IE11 in Vue 3
20 | 
21 | ### Behavior inconsistencies
22 | 
23 | Vue 2's reactivity system is based on ES5 getter/setters. Vue 3 leverages ES2015 Proxies for a more performant and complete reactivity system, which cannot be polyfilled in IE11. This is the major roadblock since it means for Vue 3 to support IE11, it essentially needs to ship two different versions with different behavior - one using the Proxy-based reactivity system, and one using ES5-getter/setter-based similar to Vue 2.
24 | 
25 | Vue 3's Proxy-based reactivity system provides near complete language feature coverage. It is able to detect many operations that are impossible or impractical to intercept in ES5, for example property addition/deletion, array indice and `length` mutations, and `in` operator checks. The same code written for the Proxy version of Vue 3 will not work in the IE11 version. Not only does this create technical complexity for us, it also creates a constant mental burden for the developers.
26 | 
27 | Our original plan was to ship both the Proxy and ES5 reactivity implementations in the development build of the IE11 version. When it is run inside a Proxy-enabled dev environment, it will detect and warn against non-IE11-compatible usage. This would work in theory, but creates an enormous amount of complexity as it requires mixing the two implementations together and risks behavior difference between development and production.
28 | 
29 | ### Long-term maintenance burden
30 | 
31 | Supporting IE11 also means we have to consider language features used in the entire codebase, and figure out proper polyfill / transpilation strategy for our distribution files. Every new feature addition that cannot be polyfilled in IE11 will create yet another behavior caveat. Once Vue 3 commits to IE11 support, it won't be able to get rid of it until the next major release.
32 | 
33 | ### Complexity for library authors
34 | 
35 | The complexity would still be somewhat acceptable if it can be fully contained within Vue itself. However, after discussing with community members, we realized the co-existence of two reactivity implementations inevitably leaks to library authors as well.
36 | 
37 | By supporting IE11 in Vue 3, library authors essentially need to make that call as well. Library authors will have to account for what build of Vue 3 their library is running with (on top of potentially also supporting Vue 2) - and if they decide to support IE11, they have to author their library with all the ES5 reactivity caveats in mind.
38 | 
39 | ### Contributing to IE11's staying power
40 | 
41 | Nobody enjoys supporting IE11. It is a dying browser stuck in the past. The further the web ecosystem moves forward, the larger the gap we need to cover when trying to support it. Ironically, by supporting IE11 in Vue 3 we are giving it more reasons to stick around. Given our user base, dropping IE11 support will likely help make it obsolete a bit faster.
42 | 
43 | ## For those who absolutely need IE11 support
44 | 
45 | We are well aware that the real demand for IE11 comes from those who are unable to upgrade: financial institutions, education sectors, and those who rely on IE11 for screen readers. If you are building an application targeting these sectors, you may not have a choice.
46 | 
47 | Our recommendation is to use Vue 2 if you need IE11 support. Instead of incurring significant technical debt for Vue 3 and future versions of Vue, we believe it would be more meaningful to redirect the effort towards backporting compatible features to Vue 2 in the 2.7 release, and ensure a closer develpment experience across the two major versions.
48 | 
49 | Some of the features that can be backport to 2.7:
50 | 
51 | - Merge the [`@vue/composition-api` plugin](https://github.com/vuejs/composition-api) into Vue 2. This will enable Composition API based libraries to directly work for both Vue 2 and Vue 3.
52 | - [`<script setup>`](https://github.com/vuejs/rfcs/pull/227) syntax in Single-File Components.
53 | - `emits` option.
54 | - Improved TypeScript typings.
55 | - Formalize Vue 2 support in Vite (currently via [non-official plugin](https://github.com/underfin/vite-plugin-vue2))
56 | 
57 | Note: the above list is tentative/non-exhaustive and will be discussed/finalized in a separate RFC.
58 | 


--------------------------------------------------------------------------------
/active-rfcs/0039-vtu-api.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 19.04.2020
  2 | - Target Major Version: 2.x
  3 | - Reference Issues: (fill in existing related issues, if any)
  4 | - Implementation PR: (leave this empty)
  5 | 
  6 | # Summary
  7 | 
  8 | VueTestUtils 2.x, which targets Vue 3, will introduce a few new methods and remove some less used ones.
  9 | 
 10 | - **Breaking:** `sync` mode removed. All `wrapper` methods return a `Promise` from `nextTick()`.
 11 | - **Breaking:** `find` is now split into `find` and `findComponent`.
 12 | - **Breaking:** Removal of some wrapper properties and methods, as they induce bad testing habits or are obsolete. 
 13 | - **Breaking:** `shallowMount` stubs defaults slots
 14 | - **Breaking:** `setProps` only works for the mounted component. 
 15 | 
 16 | **Note:** The API for VueTestUtils 1.x will stay the same and will support Vue 2.x. 
 17 | 
 18 | # Motivation
 19 | 
 20 | - Support Vue 3's Component APIs.
 21 | - Provide a smaller and easier to understand API
 22 | - Allow adding custom functionality via plugin system. [TODO]
 23 | - Remove methods that are bloat or lead to bad testing habits.
 24 | - Generally improve VTU Docs and Guides.
 25 | 
 26 | # Detailed design
 27 | 
 28 | - `createLocalVue` is removed. Vue now exposes `createApp`, which creates an isolated app instance. VTU does that under the hood.
 29 | - Fully `async`, each method that induces a mutation returns a `Promise` from `nextTick()`. Methods like `setValue` and `trigger` can be awaited, ensuring the DOM is re-rendered before each assertion.
 30 | - Rewritten completely in TypeScript, giving much improved type hints when writing tests.
 31 | - `shallowMount` will stub default slots of stubbed components. There will be an opt-in configuration to enable rendering slots for stubbed components in a similar manner to VTU beta. There is a limitation that scoped slots will not be able to provide data in such cases.
 32 | - Simple plugin system to allow extending VTU with your own methods. See [Plugins](#plugin-system)
 33 | 
 34 | ## API changes
 35 | 
 36 | We will only list the changes and deprecations. Please check the temporary [documentation](https://vuejs.github.io/vue-test-utils-next-docs/) for a full API listing.
 37 | 
 38 | ### mountOptions
 39 | 
 40 | #### props
 41 | 
 42 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#props) - Renamed from `propsData` to match component `props` field.
 43 | 
 44 | #### global
 45 | 
 46 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#global) - The `global` namespace is used to pass configuration to the `createApp` instance. Things like global components, directives and so on.
 47 | 
 48 | These settings can also be globally set via the exported `config` object - `config.global.mocks.$t = jest.fn()`.
 49 | 
 50 | - **global.components** - register global components
 51 | - **global.directives** - register a global directive
 52 | - **global.mixins** - register a global mixin
 53 | - **global.plugins** - install a plugin
 54 | - **global.stubs** - see bellow
 55 | - **global.mocks** - see bellow
 56 | - **global.provide** - see bellow
 57 | 
 58 | #### stubs 
 59 | 
 60 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#global-stubs) - Moved to `global.stubs`. 
 61 | 
 62 | - **New** - Stubs will no longer render the slots of a component. This can be enabled by a global flag `config.renderStubSlots = true`.
 63 | 
 64 | #### mocks
 65 | 
 66 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#global-mocks) - Moved to `global.mocks`
 67 | 
 68 | #### provide
 69 | 
 70 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#global-provide) - Moved to `global.provide`.
 71 | 
 72 | ### Methods
 73 | 
 74 | #### classes
 75 | 
 76 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#classes)
 77 | 
 78 | - **New** - throw error for multiple root nodes.
 79 | 
 80 | #### unmount
 81 | 
 82 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#unmount)
 83 | 
 84 | - **New** replaces `destroy` to match Vue 3 API
 85 | 
 86 | #### find
 87 | 
 88 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#find)
 89 | 
 90 | - **Breaking** - Returns only `DOMWrapper`. Cannot find Component instances. see [findComponent](#findcomponent)
 91 | - **Breaking** - Accepts query selector only. 
 92 | - **New** - Can now return instance root element, or a fragment of the root.
 93 | 
 94 | #### findAll
 95 | 
 96 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#findall)
 97 | 
 98 | - **Breaking** - Returns only array of `DOMWrapper`. 
 99 | - **Breaking** - No longer returns `WrapperArray`.
100 | - **Breaking** - Accepts query selector only. 
101 | 
102 | #### findComponent
103 | 
104 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#findcomponent)
105 | 
106 | `findComponent` can search for component instances, nested any level in your component tree. This method is most useful for edge case assertions, that are not reflected directly in the DOM
107 |  or when using `shallowMount` and asserting props on a stub.
108 |  
109 | In most cases, users will use `find` for asserting DOM properties and content. In cases where a Vue component instance is a really needed, use `findComponent`.
110 | 
111 | - **New** - finds a Vue Component instance by `ref`, `name`, `query` or Component definition. Returns `VueWrapper`.
112 | - **New** - Only available on `VueWrapper` - cannot chain off `find`.
113 | 
114 | #### findAllComponents
115 | 
116 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#findallcomponents)
117 | 
118 | - **New** - finds all Vue Components that match `name`, `query` or Component Definition. Returns array of `VueWrapper`.
119 | - **New** - Only available on `VueWrapper`.
120 | 
121 | #### setProps
122 | 
123 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#setprops)
124 | 
125 | - **Breaking** - Only works on the mounted component.
126 | - **New** - Returns `nextTick`
127 | 
128 | #### setValue
129 | 
130 | [Link](https://vuejs.github.io/vue-test-utils-next-docs/api/#setvalue)
131 | 
132 | - **Breaking** - Only works on `DOMWrapper` (for now).
133 | - **New** - Unifies `setChecked` and `setSelected`.
134 | - **New** - Returns `nextTick`
135 | 
136 | ### Plugin System
137 | 
138 | A simple plugin system is currently being discussed and prototyped here - [POC: VTU Plugin interface](https://github.com/vuejs/vue-test-utils-next/pull/82).
139 | 
140 | Thi should allow users to add extra methods to the VueWrapper and DOMWrapper classes, giving them more freedom in setting up their test suite.
141 | 
142 | ```js
143 | const plugin = (wrapper) => {
144 |   return {
145 |     width: 200,
146 |     findByTestId: (query) => wrapper.find(`[data-testid=${query}]`)
147 |   }
148 | }
149 | 
150 | config.plugins.VueWrapper.install(plugin)
151 | 
152 | // later
153 | expect(mount(Component).findByTestId('foo').exists()).toBe(true)
154 | ```
155 | 
156 | ## Deprecated
157 | 
158 | ### Methods
159 | 
160 | #### emittedByOrder
161 | 
162 | [Link](https://vue-test-utils.vuejs.org/api/wrapper/#emittedbyorder) - Rarely used, use `emitted` instead.
163 | 
164 | ```js
165 | expect(wrapper.emitted('change')[0]).toEqual(['param1', 'param2'])
166 | ```
167 | 
168 | #### is
169 | 
170 | [Link](https://vue-test-utils.vuejs.org/api/wrapper/#is) - Use `element.tagName` or the `classes()` method. Could be added as a plugin method later.
171 | 
172 | ```js
173 | expect(wrapper.element.tagName).toEqual('div')
174 | expect(wrapper.classes()).toContain('Foo')
175 | ```
176 | 
177 | #### isEmpty
178 | 
179 | [Link](https://vue-test-utils.vuejs.org/api/wrapper/#isempty) - Use custom matcher like [jest-dom#tobeempty](https://github.com/testing-library/jest-dom#tobeempty) on the element.
180 | 
181 | ```js
182 | expect(wrapper.element).toBeEmpty()
183 | ```
184 | 
185 | #### isVisible
186 | 
187 | [Link](https://vue-test-utils.vuejs.org/api/wrapper/#isvisible) - Use custom matcher like [jest-dom#tobevisible](https://github.com/testing-library/jest-dom#tobevisible)
188 | 
189 | ```js
190 | expect(wrapper.element).toBeVisible()
191 | ```
192 | 
193 | #### isVueInstance
194 | 
195 | [Link](https://vue-test-utils.vuejs.org/api/wrapper/#isvueinstance) - No longer necessary, `find` always returns an `DOMWrapper` and `findComponent` returns a `VueWrapper`. Both return `ErrorWrapper` if failed.
196 | 
197 | #### setMethods
198 | 
199 | [Link](https://vue-test-utils.vuejs.org/api/wrapper/#setmethods) - Anti-pattern. Vue does not support arbitrarily replacement of methods, nor should VTU. If you need to stub out an action, extract the hard parts away. Then you can unit test them as well.
200 | 
201 | ```js
202 | // Component.vue
203 | import { asyncAction } from 'actions'
204 | const Component = {
205 |     ...,
206 |     methods: {
207 |         async someAsyncMethod() {
208 |             this.result = await asyncAction()
209 |         }
210 |     }	
211 | }
212 | 
213 | // spec.js
214 | import { asyncAction } from 'actions'
215 | jest.mock('actions')
216 | asyncAction.mockResolvedValue({ foo: 'bar' })
217 | 
218 | // rest of your test
219 | 
220 | ```
221 | 
222 | #### setChecked and setSelected
223 |  
224 | Merged with [setValue](#setvalue)
225 | 
226 | #### destroy
227 | 
228 | Now named `unmount` to match Vue 3 API
229 | 
230 | #### name 
231 | 
232 | [Link](https://vue-test-utils.vuejs.org/api/wrapper/#name) - Removed from core. Could be added as part of extended plugin.
233 | 
234 | ### Classes and properties
235 | 
236 | - **WrapperArray** - [Link](https://vue-test-utils.vuejs.org/api/wrapper-array/) - `find` and `findComponent` will just return an array of `VueWrapper` or `DOMWrapper` respectively.
237 | - **config.methods** - [Link](https://vue-test-utils.vuejs.org/api/#methods) - Will no longer be able to replace methods.
238 | - **config.silent** - [Link](https://vue-test-utils.vuejs.org/api/#silent) - not needed.
239 | - **Wrapper.options** - [Link](https://vue-test-utils.vuejs.org/api/wrapper/#options) - not needed.
240 | 
241 | ## Not yet implemented
242 | 
243 | - **Wrapper.selector** [Link](https://vue-test-utils.vuejs.org/api/wrapper/#selector)
244 | - **Wrapper.contains** - [Link](https://vue-test-utils.vuejs.org/api/wrapper/#contains)
245 | - **shallowMount** - [Link](https://vue-test-utils.vuejs.org/api/#shallowmount) - **Stubs** work, so its halfway there.
246 | - **render** - [Link](https://vue-test-utils.vuejs.org/api/#render)
247 | - **renderToString** - [Link](https://vue-test-utils.vuejs.org/api/#rendertostring)
248 | - **createWrapper** - [Link](https://vue-test-utils.vuejs.org/api/#createwrapper-node-options)
249 | - **enableAutoDestroy** - [Link](https://vue-test-utils.vuejs.org/api/#enableautodestroy-hook)
250 | - **scopedSlots** - ScopedSlots are not ready yet. They will most probably be merged with normal ones, and will be a function with data, similar to VTU Beta.
251 | 
252 | # Drawbacks
253 | 
254 | - People will have to separate `find` into `findComponent` and `find`. We hope this would make tests easier to read and reason with.
255 | - Snapshots would have to be updated.
256 | - Some deprecated methods and functionality would have to be most likely installed via an extra plugin.
257 | 
258 | # Adoption strategy
259 | 
260 | - Rewrite docs from ground up. 
261 | - Code-mod where possible (`find` -> `findComponent` for most cases, `destroy` -> `unmount`)
262 | - Add deprecation warnings to beta before v1 release
263 | - Add dedicated guides on how to write better and more maintainable tests for popular tools like Vuex, Router etc..
264 | - Work with popular Vue ecosystem libraries and frameworks, like Quasar, Nuxt and Vuetify for better understanding of user needs.
265 | - Deprecation build with warnings. 
266 | 
267 | # Unresolved questions
268 | 
269 | - Stubs is still in development. It has many issues in VTU beta and we want to do it right this time. Will probably post a new RFC entirely for it.
270 | 


--------------------------------------------------------------------------------
/active-rfcs/0041-reactivity-effect-scope.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-08-20
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: (fill in existing related issues, if any)
  4 | - Implementation PR: [#2195](https://github.com/vuejs/vue-next/pull/2195)
  5 | 
  6 | # Summary
  7 | 
  8 | Introducing a new `effectScope()` API for `@vue/reactivity`. An `EffectScope` instance can automatically collect effects run within a synchronous function so that these effects can be disposed together at a later time.
  9 | 
 10 | # Basic example
 11 | 
 12 | ```ts
 13 | // effect, computed, watch, watchEffect created inside the scope will be collected
 14 | 
 15 | const scope = effectScope()
 16 | 
 17 | scope.run(() => {
 18 |   const doubled = computed(() => counter.value * 2)
 19 | 
 20 |   watch(doubled, () => console.log(doubled.value))
 21 | 
 22 |   watchEffect(() => console.log('Count: ', doubled.value))
 23 | })
 24 | 
 25 | // to dispose all effects in the scope
 26 | scope.stop()
 27 | ```
 28 | 
 29 | # Motivation
 30 | 
 31 | In Vue's component `setup()`, effects will be collected and bound to the current instance. When the instance get unmounted, effects will be disposed automatically. This is a convenient and intuitive feature.
 32 | 
 33 | However, when we are using them outside of components or as a standalone package, it's not that simple. For example, this might be what we need to do for disposing the effects of `computed` & `watch`
 34 | 
 35 | ```ts
 36 | const disposables = []
 37 | 
 38 | const counter = ref(0)
 39 | const doubled = computed(() => counter.value * 2)
 40 | 
 41 | disposables.push(() => stop(doubled.effect))
 42 | 
 43 | const stopWatch1 = watchEffect(() => {
 44 |   console.log(`counter: ${counter.value}`)
 45 | })
 46 | 
 47 | disposables.push(stopWatch1)
 48 | 
 49 | const stopWatch2 = watch(doubled, () => {
 50 |   console.log(doubled.value)
 51 | })
 52 | 
 53 | disposables.push(stopWatch2)
 54 | ```
 55 | 
 56 | And to stop the effects:
 57 | 
 58 | ```ts
 59 | disposables.forEach((f) => f())
 60 | disposables = []
 61 | ```
 62 | 
 63 | Especially when we have some long and complex composable code, it's laborious to manually collect all the effects. It's also easy to forget collecting them (or you don't have access to effects created in the composable functions) which might result in memory leakage and unexpected behavior.
 64 | 
 65 | This RFC is trying to abstract the component's `setup()` effect collecting and disposing feature into a more general API that can be reused outside of the component model.
 66 | 
 67 | It also provides the functionality to create "detached" effects from the component's `setup()` scope or user-defined scope. Resolving https://github.com/vuejs/vue-next/issues/1532.
 68 | 
 69 | # Detailed Design
 70 | 
 71 | ### New API Summary
 72 | 
 73 | - `effectScope(detached = false): EffectScope`
 74 | 
 75 |   ```ts
 76 |   interface EffectScope {
 77 |     run<T>(fn: () => T): T | undefined // undefined if scope is inactive
 78 |     stop(): void
 79 |   }
 80 |   ```
 81 | 
 82 | - `getCurrentScope(): EffectScope | undefined`
 83 | - `onScopeDispose(fn: () => void): void`
 84 | 
 85 | ### Basic Usage
 86 | 
 87 | Creating a scope:
 88 | 
 89 | ```ts
 90 | const scope = effectScope()
 91 | ```
 92 | 
 93 | A scope can run a function and will capture all effects created during the function's synchronous execution, including any API that creates effects internally, e.g. `computed`, `watch` and `watchEffect`:
 94 | 
 95 | ```ts
 96 | scope.run(() => {
 97 |   const doubled = computed(() => counter.value * 2)
 98 | 
 99 |   watch(doubled, () => console.log(doubled.value))
100 | 
101 |   watchEffect(() => console.log('Count: ', doubled.value))
102 | })
103 | 
104 | // the same scope can run multiple times
105 | scope.run(() => {
106 |   watch(counter, () => {
107 |     /*...*/
108 |   })
109 | })
110 | ```
111 | 
112 | The `run` method also forwards the return value of the executed function:
113 | 
114 | ```js
115 | console.log(scope.run(() => 1)) // 1
116 | ```
117 | 
118 | When `scope.stop()` is called, it will stop all the captured effects and nested scopes recursively.
119 | 
120 | ```ts
121 | scope.stop()
122 | ```
123 | 
124 | ### Nested Scopes
125 | 
126 | Nested scopes should also be collected by their parent scope. And when the parent scope gets disposed, all its descendant scopes will also be stopped.
127 | 
128 | ```ts
129 | const scope = effectScope()
130 | 
131 | scope.run(() => {
132 |   const doubled = computed(() => counter.value * 2)
133 | 
134 |   // not need to get the stop handler, it will be collected by the outer scope
135 |   effectScope().run(() => {
136 |     watch(doubled, () => console.log(doubled.value))
137 |   })
138 | 
139 |   watchEffect(() => console.log('Count: ', doubled.value))
140 | })
141 | 
142 | // dispose all effects, including those in the nested scopes
143 | scope.stop()
144 | ```
145 | 
146 | ### Detached Nested Scopes
147 | 
148 | `effectScope` accepts an argument to be created in "detached" mode. A detached scope will not be collected by its parent scope.
149 | 
150 | This also makes usages like ["lazy initialization"](https://github.com/vuejs/vue-next/issues/1532) possible.
151 | 
152 | ```ts
153 | let nestedScope
154 | 
155 | const parentScope = effectScope()
156 | 
157 | parentScope.run(() => {
158 |   const doubled = computed(() => counter.value * 2)
159 | 
160 |   // with the detected flag,
161 |   // the scope will not be collected and disposed by the outer scope
162 |   nestedScope = effectScope(true /* detached */)
163 |   nestedScope.run(() => {
164 |     watch(doubled, () => console.log(doubled.value))
165 |   })
166 | 
167 |   watchEffect(() => console.log('Count: ', doubled.value))
168 | })
169 | 
170 | // disposes all effects, but not `nestedScope`
171 | parentScope.stop()
172 | 
173 | // stop the nested scope only when appropriate
174 | nestedScope.stop()
175 | ```
176 | 
177 | ### `onScopeDispose`
178 | 
179 | The global hook `onScopeDispose()` serves a similar functionality to `onUnmounted()`, but works for the current scope instead of the component instance. This could benefit composable functions to clean up their side effects along with its scope. Since `setup()` also creates a scope for the component, it will be equivalent to `onUnmounted()` when there is no explicit effect scope created.
180 | 
181 | ```ts
182 | import { onScopeDispose } from 'vue'
183 | 
184 | const scope = effectScope()
185 | 
186 | scope.run(() => {
187 |   onScopeDispose(() => {
188 |     console.log('cleaned!')
189 |   })
190 | })
191 | 
192 | scope.stop() // logs 'cleaned!'
193 | ```
194 | 
195 | ### Getting the Current Scope
196 | 
197 | A new API `getCurrentScope()` is introduced to get the current scope.
198 | 
199 | ```ts
200 | import { getCurrentScope } from 'vue'
201 | 
202 | getCurrentScope() // EffectScope | undefined
203 | ```
204 | 
205 | ## Use Case Examples
206 | 
207 | ### Example A: Shared Composable
208 | 
209 | Some composables setup global side effects. For example the following `useMouse()` function:
210 | 
211 | ```ts
212 | function useMouse() {
213 |   const x = ref(0)
214 |   const y = ref(0)
215 | 
216 |   function handler(e) {
217 |     x.value = e.x
218 |     y.value = e.y
219 |   }
220 | 
221 |   window.addEventListener('mousemove', handler)
222 | 
223 |   onUnmounted(() => {
224 |     window.removeEventListener('mousemove', handler)
225 |   })
226 | 
227 |   return { x, y }
228 | }
229 | ```
230 | 
231 | If `useMouse()` is called in multiple components, each component will attach a `mousemove` listener and create its own copy of `x` and `y` refs. We should be able to make this more efficient by sharing the same set of listeners and refs across multiple components, but we can't because each `onUnmounted` call is coupled to a single component instance.
232 | 
233 | We can achieve this using detached scope, and `onScopeDispose`. First, we need to replace `onUnmounted` with `onScopeDispose`:
234 | 
235 | ```diff
236 | - onUnmounted(() => {
237 | + onScopeDispose(() => {
238 |   window.removeEventListener('mousemove', handler)
239 | })
240 | ```
241 | 
242 | This still works because a Vue component now also runs its `setup()` inside a scope, which will be disposed when the component is unmounted.
243 | 
244 | Then, we can create a utility function that manages parent scope subscriptions:
245 | 
246 | ```ts
247 | function createSharedComposable(composable) {
248 |   let subscribers = 0
249 |   let state, scope
250 | 
251 |   const dispose = () => {
252 |     if (scope && --subscribers <= 0) {
253 |       scope.stop()
254 |       state = scope = null
255 |     }
256 |   }
257 | 
258 |   return (...args) => {
259 |     subscribers++
260 |     if (!state) {
261 |       scope = effectScope(true)
262 |       state = scope.run(() => composable(...args))
263 |     }
264 |     onScopeDispose(dispose)
265 |     return state
266 |   }
267 | }
268 | ```
269 | 
270 | Now we can create a shared version of `useMouse`:
271 | 
272 | ```ts
273 | const useSharedMouse = createSharedComposable(useMouse)
274 | ```
275 | 
276 | The new `useSharedMouse` composable will set up the listener only once no matter how many components are using it, and removes the listener when no component is using it anymore. In fact, the `useMouse` function should probably be a shared composable in the first place!
277 | 
278 | ### Example B: Ephemeral Scopes
279 | 
280 | ```ts
281 | export default {
282 |   setup() {
283 |     const enabled = ref(false)
284 |     let mouseState, mouseScope
285 | 
286 |     const dispose = () => {
287 |       mouseScope && mouseScope.stop()
288 |       mouseState = null
289 |     }
290 | 
291 |     watch(
292 |       enabled,
293 |       () => {
294 |         if (enabled.value) {
295 |           mouseScope = effectScope()
296 |           mouseState = mouseScope.run(() => useMouse())
297 |         } else {
298 |           dispose()
299 |         }
300 |       },
301 |       { immediate: true }
302 |     )
303 | 
304 |     onScopeDispose(dispose)
305 |   },
306 | }
307 | ```
308 | 
309 | In the example above, we would create and dispose some scopes on the fly, `onScopeDispose` allow `useMouse` to do the cleanup correctly while `onUnmounted` would never be called during this process.
310 | 
311 | ## Affected Usage in Vue Core
312 | 
313 | Currently in `@vue/runtime-dom`, [we wrap the `computed` to add the instance binding](https://github.com/vuejs/vue-next/blob/master/packages/runtime-core/src/apiComputed.ts). This makes the following statements NOT equivalent
314 | 
315 | ```ts
316 | // not the same
317 | import { computed } from '@vue/reactivity'
318 | import { computed } from 'vue'
319 | ```
320 | 
321 | This should not be an issue for most of the users, but for some libraries that would like to only rely on `@vue/reactivity` (for more flexible usages), this might be a pitfall and cause some unwanted side-effects.
322 | 
323 | With this RFC, `@vue/runtime-dom` can use the `effectScope` to collect the effects directly and computed rewrapping will not be necessary anymore.
324 | 
325 | ```ts
326 | // with the RFC, `vue` simply redirect `computed` from `@vue/reactivity`
327 | import { computed } from '@vue/reactivity'
328 | import { computed } from 'vue'
329 | ```
330 | 
331 | # Drawbacks
332 | 
333 | - It doesn't work well with async functions
334 | 
335 | # Alternatives
336 | 
337 | M/A
338 | 
339 | # Adoption strategy
340 | 
341 | This is a new API and should not affect the existing code. It's also a low-level API only intended for advanced users and library authors.
342 | 
343 | # Unresolved questions
344 | 
345 | None
346 | 


--------------------------------------------------------------------------------
/active-rfcs/0042-expose-api.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-09-06
  2 | - Target Major Version: 3.x
  3 | - Reference Issues: #135, #210
  4 | 
  5 | # Summary
  6 | 
  7 | Provide the ability for components to control what is publicly exposed on its component instance. This proposal unifies #135 and #210 with additional details.
  8 | 
  9 | # Basic example
 10 | 
 11 | ## Options API
 12 | 
 13 | ```js
 14 | export default {
 15 |   expose: ['increment'],
 16 | 
 17 |   data() {
 18 |     return {
 19 |       count: 0
 20 |     }
 21 |   },
 22 |   methods: {
 23 |     increment() {
 24 |       this.count++
 25 |     }
 26 |   }
 27 | }
 28 | ```
 29 | 
 30 | ## Composition API
 31 | 
 32 | ```javascript
 33 | import { ref } from 'vue'
 34 | 
 35 | export default {
 36 |   setup(props, { expose }) {
 37 |     const count = ref(0)
 38 | 
 39 |     function increment() {
 40 |       count.value++
 41 |     }
 42 | 
 43 |     // public
 44 |     expose({
 45 |       increment
 46 |     })
 47 | 
 48 |     // private
 49 |     return { increment, count }
 50 |   }
 51 | }
 52 | ```
 53 | 
 54 | Here in the both cases, other components would only be able to access the `increment` method from this component, and nothing else.
 55 | 
 56 | # Motivation
 57 | 
 58 | In Vue, we have a few ways to retrieve the "public instance" of a component:
 59 | 
 60 | - Via template refs
 61 | - Via the `$parent` or `$root` properties
 62 | 
 63 | Up until now, the concept of the "public instance" is equivalent to the `this` context inside a component. However, this creates a number of issues:
 64 | 
 65 | 1. A component's public and internal interface isn't always the same. A component may have internal properties that it doesn't want to expose to other components. In other cases a component may want to expose methods that are specifically meant to be used by other components.
 66 | 
 67 | 2. A component returning render function from `setup()` encloses all its state inside the `setup()` closure, so nothing is exposed on the public instance, and there's currently no way to selectively expose properties while using this pattern.
 68 | 
 69 | 3. `<script setup>` is also compiled into (2) so has the same issue.
 70 | 
 71 | The proposed APIs solve these issues by giving components the ability to explicitly declare publicly exposed properties.
 72 | 
 73 | # Detailed design
 74 | 
 75 | ## Options API
 76 | 
 77 | A new option, `expose` is introduced. It expects an array of property keys to be exposed:
 78 | 
 79 | ```js
 80 | // Child.vue
 81 | export default {
 82 |   expose: ['increment'],
 83 | 
 84 |   data() {
 85 |     return {
 86 |       count: 0
 87 |     }
 88 |   },
 89 |   methods: {
 90 |     increment() {
 91 |       this.count++
 92 |     }
 93 |   }
 94 | }
 95 | ```
 96 | 
 97 | In a parent component:
 98 | 
 99 | ```html
100 | <Child ref="child" />
101 | ```
102 | 
103 | ```js
104 | this.$refs.child.increment() // ok
105 | this.$refs.child.count // undefined
106 | ```
107 | 
108 | If `expose` is an empty array, then the component would be considered "closed" and no properties would be exposed.
109 | 
110 | > **Note:** `expose` option is only respected in the base component and ignored when used in mixins.
111 | 
112 | ## Composition API
113 | 
114 | In Composition API, the 2nd argument of `setup` (aka the "setup context") now also provides the `expose` method:
115 | 
116 | ```js
117 | import { ref } from 'vue'
118 | 
119 | export default {
120 |   setup(props, { expose }) {
121 |     const count = ref(0)
122 | 
123 |     function increment() {
124 |       count.value++
125 |     }
126 | 
127 |     // public
128 |     expose({
129 |       increment
130 |     })
131 | 
132 |     // private
133 |     return { increment, count }
134 |   }
135 | }
136 | ```
137 | 
138 | The `expose` method expects an object of the actual values to be exposed.
139 | 
140 | ### In `<script setup>`
141 | 
142 | The `defineExpose()` macro compiles into runtime `expose()` call.
143 | 
144 | ```html
145 | <script setup>
146 |   const count = ref(0)
147 | 
148 |   function increment() {
149 |     count.value++
150 |   }
151 | 
152 |   defineExpose({
153 |     increment
154 |   })
155 | </script>
156 | ```
157 | 
158 | See [relevant section](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0040-script-setup.md#exposing-components-public-interface) in the `<script setup>` RFC.
159 | 
160 | ### Exposed Ref Unwrapping Behavior
161 | 
162 | Note the exposed instance unwraps refs similar to the normal public instance:
163 | 
164 | ```js
165 | // in child
166 | const count = ref(0)
167 | expose({
168 |   count
169 | })
170 | ```
171 | 
172 | ```js
173 | // in parent
174 | this.$refs.child.count // 0
175 | ```
176 | 
177 | ## Limiting Expose Control to Base Component
178 | 
179 | As raised in the discussions for a previous draft (#210), it would be very confusing if mixins and external composition functions are able to expose arbitrary properties. Therefore, the API is designed to restrict the capability to the base component only:
180 | 
181 | - The `expose` option is ignored when encountered in `mixins` or `extends` sources.
182 | - The Composition API `expose` function is provided via the setup context instead of a global API (so that it cannot be imported in external composition functions) and can only be called once.
183 | 
184 | ## Additionally Exposed Properties
185 | 
186 | An experimental implementation has been shipped in prior versions and we found in some cases there are patterns or tools (e.g. `vue-test-utils`) that relies on the presence of Vue built-in instance properties like `$el` or `$refs`.
187 | 
188 | The public instance with explicit `expose` thus still exposes these built-in instance properties.
189 | 
190 | # Drawbacks
191 | 
192 | N/A
193 | 
194 | # Alternatives
195 | 
196 | N/A
197 | 
198 | # Adoption strategy
199 | 
200 | This feature is additive and doesn't affect existing usage.
201 | 
202 | # Unresolved Questions
203 | 
204 | ## Type Inference
205 | 
206 | Currently no Vue tooling has the ability to infer types of child component instances obtained from a ref.
207 | 
208 | A workaround is to explicitly export the public interface from the child component:
209 | 
210 | ```html
211 | <!-- Child.vue -->
212 | <script lang="ts">
213 |   export interface Api {
214 |     // ...
215 |   }
216 | </script>
217 | ```
218 | 
219 | In parent:
220 | 
221 | ```html
222 | <script setup lang="ts">
223 |   import { ref } from 'vue'
224 |   import Child from './Child.vue'
225 |   import type { Api } from './Child.vue'
226 | 
227 |   const childRef = ref<Api>()
228 | </script>
229 | 
230 | <template>
231 |   <Child ref="childRef" />
232 | </template>
233 | ```
234 | 
235 | The above does not affect the runtime API design and therefore should not block this RFC from being merged.
236 | 


--------------------------------------------------------------------------------
/active-rfcs/0043-sfc-style-variables.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2020-06-29
  2 | - Target Major Version: 2.x & 3.x
  3 | - Reference Issues: N/A
  4 | - Implementation PR: N/A
  5 | 
  6 | # Summary
  7 | 
  8 | Support using component-state-driven CSS variables into Single File Components styles.
  9 | 
 10 | # Basic example
 11 | 
 12 | ```html
 13 | <template>
 14 |   <div class="text">hello</div>
 15 | </template>
 16 | 
 17 | <script>
 18 |   export default {
 19 |     data() {
 20 |       return {
 21 |         color: 'red',
 22 |         font: {
 23 |           size: '2em',
 24 |         },
 25 |       }
 26 |     },
 27 |   }
 28 | </script>
 29 | 
 30 | <style>
 31 |   .text {
 32 |     color: v-bind(color);
 33 | 
 34 |     /* expressions (wrap in quotes) */
 35 |     font-size: v-bind('font.size');
 36 |   }
 37 | </style>
 38 | ```
 39 | 
 40 | # Motivation
 41 | 
 42 | Vue SFC styles provide straightforward CSS collocation and encapsulation, but it is purely static - which means up to this point we have no capability of dynamically updating the styles at runtime based on the component's state.
 43 | 
 44 | Now with [most modern browsers supporting native CSS variables](https://caniuse.com/#feat=css-variables), we can leverage it to easily connect the component's state and styles.
 45 | 
 46 | # Detailed design
 47 | 
 48 | The `<style>` tag in an SFC now supports a custom CSS function named `v-bind`:
 49 | 
 50 | ```html
 51 | <!-- in Vue SFC -->
 52 | <style>
 53 |   .text {
 54 |     color: v-bind(color);
 55 |   }
 56 | </style>
 57 | ```
 58 | 
 59 | As expected, this would bind the `color` declaration's value to the `color` property of the component's state, reactively.
 60 | 
 61 | The `v-bind` function can support arbitrary JavaScript expressions inside, but since JavaScript expressions may contain characters that are not valid in CSS identifiers, they will need to be wrapped in quotes most of the time:
 62 | 
 63 | ```css
 64 | .text {
 65 |   font-size: v-bind('theme.font.size');
 66 | }
 67 | ```
 68 | 
 69 | When such CSS variables are detected, the SFC compiler will perform the following:
 70 | 
 71 | 1. Rewrite the `v-bind()` to a native `var()` with a hashed variable name. The above will be rewritten to:
 72 | 
 73 |    ```css
 74 |     .text {
 75 |       color: var(--6b53742-color);
 76 |       font-size: var(--6b53742-theme_font_size);
 77 |     }
 78 |    ```
 79 | 
 80 |    Note the hashing will be applied in all cases, regardless of whether `<style>` tag is scoped or not. This means injected CSS variables will never accidentally leak into child components.
 81 | 
 82 | 2. The corresponding variables will be injected to the component's root element as inline styles. For the example above, the final rendered DOM will look like this:
 83 | 
 84 |    ```html
 85 |    <div style="--6b53742-color:red;--6b53742-theme_font_size:2em;" class="text">
 86 |      hello
 87 |    </div>
 88 |    ```
 89 | 
 90 |    The injection is reactive - so if the component's `color` property changes, the injected CSS variable will be updated accordingly. This update is applied independent of the component's template update so changes to a CSS-only reactive property won't trigger template re-renders.
 91 | 
 92 | ## Compilation Details
 93 | 
 94 | - In order to inject the CSS variables, the compiler needs to generate and inject code like the following into the component's `setup()` function:
 95 | 
 96 |   ```js
 97 |   import { useCssVars } from 'vue'
 98 | 
 99 |   export default {
100 |     setup() {
101 |       // ...
102 |       useCssVars((_ctx) => ({
103 |         color: _ctx.color,
104 |         theme_font_size: _ctx.theme.font.size,
105 |       }))
106 |     },
107 |   }
108 |   ```
109 | 
110 |   ...where the `useCssVars` runtime helper sets up a `watchEffect` to reactively apply the variables to the DOM.
111 | 
112 | - The compilation strategy requires the script compilation to do a simple regex parse of the `<style>` tag content first in order to determine the list of variables to expose. However, this parse phase won't be as costly as a full AST-based parse.
113 | 
114 | - In production, the variable names can be further hashed to reduce CSS footprint:
115 | 
116 |    ```css
117 |     .text {
118 |       color: var(--x3b2fs2);
119 |       font-size: var(--29fh29g);
120 |     }
121 |    ```
122 | 
123 |    Corresponding generated JavaScript code will be using the same hashes accordingly.
124 | 
125 | # Adoption strategy
126 | 
127 | This is a fully backwards compatible new feature. However, we should make it clear that it relies on native CSS variables so the user needs to be aware of the browser support range.
128 | 


--------------------------------------------------------------------------------
/active-rfcs/0044-router-push-history-state.md:
--------------------------------------------------------------------------------
  1 | - Start Date: 2021-10-15
  2 | - Target Major Version: Router 4.x
  3 | - Reference Issues: https://github.com/vuejs/vue-router/issues/2243
  4 | - Implementation PR: (leave this empty)
  5 | 
  6 | # Summary
  7 | 
  8 | - Allow the user to pass a `state` property alongside `path`, `query`, and other properties to persist to `history.state`.
  9 | - Allow the user to read the `history.state` directly at `this.$route.state`.
 10 | 
 11 | # Basic example
 12 | 
 13 | Programmatic navigation:
 14 | 
 15 | ```js
 16 | router.push({ name: 'Details', state: { showModal: true } })
 17 | router.replace({ state: { showModal: true } })
 18 | ```
 19 | 
 20 | Declarative:
 21 | 
 22 | ```vue
 23 | <router-link
 24 |   :to="{ name: 'Details', state: { showModal: true } }"
 25 | >Show Details</router-link>
 26 | ```
 27 | 
 28 | # Motivation
 29 | 
 30 | Passing _state_ through the `history` API is a native feature that is currently hard to use when using Vue Router. While it has its limitations, it has many useful usecases like showing modals and can be use as a source of truth for state that is specific to certain locations and **should be persisted** across navigations when **coming back** to a previously visited page.
 31 | 
 32 | Currently, this can be achieved most of the times with
 33 | 
 34 | ```js
 35 | // check for the navigation to succeed
 36 | if (!(await router.push('/somewhere'))) {
 37 |   history.replaceState({ ...history.state, ...newState }, '')
 38 | }
 39 | ```
 40 | 
 41 | It currently cannot be achieved if the current location is the same and the only thing we want to do is _modify_ the state.
 42 | 
 43 | The router should facilitate using the features of the History API but currently it turns out to make the task of _writing to `history.state`_ difficult or impossible (e.g. same location navigation)
 44 | 
 45 | # Detailed design
 46 | 
 47 | ## Writing to `history.state`
 48 | 
 49 | Vue Router 4 already uses `history.state` internally to detect navigation direction and revert UI initiated navigations such as the back and forward button. In order to not interfere with the information stored by it, it should save the state passed by the user to a nested property:
 50 | 
 51 | ```js
 52 | // somewhere inside the router code
 53 | history.pushState({ ...routerState, userState: state }, '', url)
 54 | ```
 55 | 
 56 | ### Duplicated navigations
 57 | 
 58 | By default, the router avoids any duplicated navigation (e.g. clicking multiple times on the same link) or calling `router.push('/somewhere')` when we are already at `/somewhere`. When `state` is passed to `router.push()` (or `router.replace()`), the router should **always create a new navigation**. This creates a hidden way to force a navigation to the same location and also the possibility to have multiple entries on the history stack that point to the same URL but this should be fine as they should contain different state.
 59 | 
 60 | 1. User goes to `/search`
 61 | 2. User clicks on button that does `router.push({ state: { searchResults: [] }})`
 62 | 3. User stays at `/search` but the page can use the passed state to display a different version
 63 | 4. User clicks the _back_ button, they stay at `/search` but see a different version of the page
 64 | 
 65 | ### Invalid state properties
 66 | 
 67 | Since [the state must be serializable](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState), some _key_ or _property_ values are invalid and should be avoided (e.g. DOM nodes or complex objects, functions, Symbols). Vue Router **won't touch the state given by the user** and pass it _as is_ to `history.pushState()`. The developer is responsible for this and must be aware that browsers might treat some Data Structures differently.
 68 | 
 69 | ### SSR
 70 | 
 71 | Since this feature only works with the History API, any given `state` property passed to `router.push()` will be ignored during SSR by the _Memory History_ implementation.
 72 | 
 73 | ## Reading the state
 74 | 
 75 | It would be convenient to be able to read the `history.state` directly from the current route because that would make it _reactive_ and allow watching or creating computed properties based on it:
 76 | 
 77 | ```js
 78 | const route = useRoute()
 79 | 
 80 | const showModal = computed(() => route.state.showModal)
 81 | ```
 82 | 
 83 | ```vue
 84 | <Modal v-if="$route.state.showModal" />
 85 | ```
 86 | 
 87 | For convenience reasons, the `route.state` property should be an empty object by default.
 88 | 
 89 | This introduces **a new TS interface to represent the current location** as the History API only allows reading from the current entry. Therefore **`from.state` is unavailable** in Navigation guards while `to.state` can be available:
 90 | 
 91 | ```ts
 92 | router.beforeEach((to, from) => {
 93 |   to.state // undefined | unknown
 94 |   from.state // TS Error property doesn't exist
 95 | })
 96 | ```
 97 | 
 98 | # Drawbacks
 99 | 
100 | - The History API has its own limitations and inconsistencies among browsers and they sometimes vary (e.g. the way state is persisted to disk and how objects are cloned). This could be a foot shot if not documented properly in terms of usage. For instance, it should be avoided to store big amounts of data that should go in component state or in a store
101 | - Making `route.state` retrieve only `history.state.userState` allows us to not expose the information stored by the router (since it's not public API) but also doesn't allow information stored in the `history.state` by other libraries. I think this is okay because the user can create a computed property to read from those properties with `computed(() => route && history.state.myOwnProperty)`.
102 | 
103 | # Alternatives
104 | 
105 | - The `route.state` property could be `undefined` when not set.
106 | - Letting `route.state` be the whole `history.state` instead of what the user passed
107 | 
108 | # Adoption strategy
109 | 
110 | Currently Vue Router 4 allows passing a `state` property to `router.push()` but the API is not documented and marked as `@internal` and should therefore not be used. Other than that, this API is an addition.
111 | 
112 | # Unresolved questions
113 | 


--------------------------------------------------------------------------------