feat: document is vue: prefix usage, deprecate v-is

Author: yyx990803

src/api/directives.md

@@ -454,31 +454,6 @@
 - **See also:**
   - [Data Binding Syntax - interpolations](../guide/template-syntax.html#text)
 
-## v-is
+## v-is <Badge text="deprecated" type="warning" />
 
-> Note: this section only affects cases where Vue templates are directly written in the page's HTML.
-
-- **Expects:** string literal
-
-- **Limited to:** native HTML elements
-
-- **Usage:** 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. As a workaround, we can use `v-is` directive on these elements:
-
-```html
-<table>
-  <tr v-is="'blog-post-row'"></tr>
-</table>
-```
-
-:::warning
-`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:
-
-```html
-<!-- Incorrect, nothing will be rendered -->
-<tr v-is="blog-post-row"></tr>
-
-<!-- Correct -->
-<tr v-is="'blog-post-row'"></tr>
-```
-
-:::
+Deprecated in 3.1.0. Use [`is` attribute with `vue:` prefix](/api/special-attributes.html#is) instead.

src/api/special-attributes.md

@@ -56,15 +56,27 @@
 
 - **Expects:** `string | Object (component’s options object)`
 
-Used for [dynamic components](../guide/component-dynamic-async.html).
+  Used for [dynamic components](../guide/component-dynamic-async.html).
 
-For example:
+  For example:
+
+  ```html
+  <!-- component changes when currentView changes -->
+  <component :is="currentView"></component>
+  ```
+
+- **Usage on native elements** <Badge text="3.1+" />
 
-```html
-<!-- component changes when currentView changes -->
-<component :is="currentView"></component>
-```
+  When the `is` attribute is used on native HTML elements, it will be interpreted as [Customized built-in elements](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-customized-builtin-example) which is a native web platform feature.
+
+  There is, however, a use case where you may need Vue to replace a native element with a Vue component, as explained in [DOM Template Parsing Caveats](/guide/component-basics.html#dom-template-parsing-caveats). You can prefix the value of the `is` attribute with `vue:` so that Vue will render the element as a Vue component instead:
+
+  ```html
+  <table>
+    <tr is="vue:my-row-component"></tr>
+  </table>
+  ```
 
 - **See also:**
   - [Dynamic Components](../guide/component-dynamic-async.html)
-  - [DOM Template Parsing Caveats](../guide/component-basics.html#dom-template-parsing-caveats)
+  - [RFC explaining the change from Vue 2](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0027-custom-elements-interop.md#customized-built-in-elements)

src/guide/component-basics.md

@@ -406,6 +406,18 @@ That's all you need to know about dynamic components for now, but once you've fi
 
 ## DOM Template Parsing Caveats
 
+If you are writing your Vue templates directly in the DOM, Vue will have to retrieve the template string from the DOM. This leads to some caveats due to browser's native HTML parsing behavior.
+
+:::tip
+It should be noted that the limitations discussed below only applies if you are writing your templates directly in the DOM. They do NOT apply if you are using string templates from the following sources:
+
+- String templates (e.g. `template: '...'`)
+- [Single-file (`.vue`) components](single-file-component.html)
+- `<script type="text/x-template">`
+:::
+
+### Element Placement Restrictions
+
 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.
 
 This will lead to issues when using components with elements that have such restrictions. For example:
@@ -416,28 +428,21 @@ This will lead to issues when using components with elements that have such rest
 </table>
 ```
 
-The custom component `<blog-post-row>` will be hoisted out as invalid content, causing errors in the eventual rendered output. We can use the special `v-is` directive as a workaround:
+The custom component `<blog-post-row>` will be hoisted out as invalid content, causing errors in the eventual rendered output. We can use the special [`is` attribute](/api/special-attributes.html#is) as a workaround:
 
 ```html
 <table>
-  <tr v-is="'blog-post-row'"></tr>
+  <tr is="vue:blog-post-row"></tr>
 </table>
 ```
 
-:::warning
-The `v-is` value is treated as a JavaScript expression, so we need to wrap the component name in quotes:
-
-```html
-<!-- Incorrect, nothing will be rendered -->
-<tr v-is="blog-post-row"></tr>
-
-<!-- Correct -->
-<tr v-is="'blog-post-row'"></tr>
-```
-
+:::tip
+When used on native HTML elements, the value of `is` must be prefixed with `vue:` in order to be interpreted as a Vue component. This is required to avoid confusion with native [customized built-in elements](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-customized-builtin-example).
 :::
 
-Also, HTML attribute names are case-insensitive, so browsers will interpret any uppercase characters as lowercase. That means when you’re using in-DOM templates, camelCased prop names and event handler parameters need to use their kebab-cased (hyphen-delimited) equivalents:
+### Case Insensivitity
+
+HTML attribute names are case-insensitive, so browsers will interpret any uppercase characters as lowercase. That means when you’re using in-DOM templates, camelCased prop names and event handler parameters need to use their kebab-cased (hyphen-delimited) equivalents:
 
 ```js
 // camelCase in JavaScript
@@ -456,12 +461,6 @@ app.component('blog-post', {
 <blog-post post-title="hello!"></blog-post>
 ```
 
-It should be noted that **these limitations do _not_ apply if you are using string templates from one of the following sources**:
-
-- String templates (e.g. `template: '...'`)
-- [Single-file (`.vue`) components](single-file-component.html)
-- `<script type="text/x-template">`
-
 That's all you need to know about DOM template parsing caveats for now - and actually, the end of Vue's _Essentials_. Congratulations! There's still more to learn, but first, we recommend taking a break to play with Vue yourself and build something fun.
 
 Once you feel comfortable with the knowledge you've just digested, we recommend coming back to read the full guide on [Dynamic & Async Components](component-dynamic-async.html), as well as the other pages in the Components In-Depth section of the sidebar.