keepalive and wip badges

Author: yyx990803

src/guide/best-practices/performance.md

@@ -2,7 +2,7 @@
 aside: deep
 ---
 
-# Performance Guide
+# Performance Guide <Badge text="WIP" />
 
 ## Page Load Performance
 

src/guide/best-practices/production-deployment.md

@@ -1,4 +1,4 @@
-# Production Deployment
+# Production Deployment <Badge text="WIP" />
 
 ## Development vs. Production
 

src/guide/built-ins/keep-alive-demos/CompA.vue

@@ -0,0 +1,9 @@
+<script setup>
+let count = $ref(0)
+</script>
+
+<template>
+  <p>Current component: A</p>
+  <span style="margin-right:20px">count: {{ count }}</span>
+  <button @click="count++">+</button>
+</template>

src/guide/built-ins/keep-alive-demos/CompB.vue

@@ -0,0 +1,9 @@
+<script setup>
+let msg = $ref('')
+</script>
+
+<template>
+  <p>Current component: B</p>
+  <span style="margin-right:20px;">Message is: {{ msg }}</span>
+  <input v-model="msg">
+</template>

src/guide/built-ins/keep-alive-demos/SwitchComponent.vue

@@ -0,0 +1,23 @@
+<script setup>
+import CompA from './CompA.vue'
+import CompB from './CompB.vue'
+
+let current = $shallowRef(CompA)
+
+const { useKeepAlive } = defineProps(['useKeepAlive'])
+</script>
+
+<template>
+  <div class="demo">
+    <label><input type="radio" v-model="current" :value="CompA" /> A</label>
+    <label><input type="radio" v-model="current" :value="CompB" /> B</label>
+    <template v-if="useKeepAlive">
+      <component :is="current"></component>
+    </template>
+    <template v-else>
+      <KeepAlive>
+        <component :is="current"></component>
+      </KeepAlive>
+    </template>
+  </div>
+</template>

src/guide/built-ins/keep-alive.md

@@ -1,40 +1,82 @@
+<script setup>
+import SwitchComponent from './keep-alive-demos/SwitchComponent.vue'
+</script>
+
 # KeepAlive
 
 ## Basic Usage
 
-:::tip
-When used in [DOM templates](/guide/essentials/component-basics.html#dom-template-parsing-caveats), it should be referenced as `<keep-alive>`.
-:::
-
-Earlier, we used the `is` attribute to switch between components in a tabbed interface:
+In the Component Basics chapter, we introduced the syntax for [Dynamic Components](/guide/essentials/component-basics.html#dynamic-components), using the `<component>` special element:
 
 ```vue-html
-<component :is="currentTabComponent"></component>
+<component :is="activeComponent" />
 ```
 
-When switching between these components though, you'll sometimes want to maintain their state or avoid re-rendering for performance reasons. For example, when expanding our tabbed interface a little:
+By default, an active component instance will be unmounted when switched away from. This will cause any changed state it holds to be lost.
+
+In the example below, we have two stateful components - A contains a counter, while B contains a message synced with an input via `v-model`. Try update the state of one of them, switch away, and then switch back to it:
 
-<!-- <common-codepen-snippet title="Dynamic components: without keep-alive" slug="jOPjZOe" tab="html,result" /> -->
+<SwitchComponent />
 
-You'll notice that if you select a post, switch to the _Archive_ tab, then switch back to _Posts_, it's no longer showing the post you selected. That's because each time you switch to a new tab, Vue creates a new instance of the `currentTabComponent`.
+You'll notice that when switched back, the previous changed state would have been reset.
 
-Recreating dynamic components is normally useful behavior, but in this case, we'd really like those tab component instances to be cached once they're created for the first time. To solve this problem, we can wrap our dynamic component with a `<keep-alive>` element:
+Creating fresh component instance on switch is normally useful behavior, but in this case, we'd really like the two component instances to be preserved even when they are inactive. To solve this problem, we can wrap our dynamic component with the `<KeepAlive>` built-in component:
 
 ```vue-html
 <!-- Inactive components will be cached! -->
-<keep-alive>
-  <component :is="currentTabComponent"></component>
-</keep-alive>
+<KeepAlive>
+  <component :is="activeComponent" />
+</KeepAlive>
 ```
 
-Check out the result below:
+Now, the state will be persisted across component switches:
 
-<!-- <common-codepen-snippet title="Dynamic components: with keep-alive" slug="VwLJQvP" tab="html,result" /> -->
+<SwitchComponent use-KeepAlive />
 
-Now the _Posts_ tab maintains its state (the selected post) even when it's not rendered.
+<div class="composition-api">
 
-Check out more details on `<keep-alive>` in the [API reference](/api/built-in-components.html#keep-alive).
+[Try it in the Playground](https://sfc.vuejs.org/#eyJBcHAudnVlIjoiPHNjcmlwdCBzZXR1cD5cbmltcG9ydCB7IHNoYWxsb3dSZWYgfSBmcm9tICd2dWUnXG5pbXBvcnQgQ29tcEEgZnJvbSAnLi9Db21wQS52dWUnXG5pbXBvcnQgQ29tcEIgZnJvbSAnLi9Db21wQi52dWUnXG5cbmNvbnN0IGN1cnJlbnQgPSBzaGFsbG93UmVmKENvbXBBKVxuPC9zY3JpcHQ+XG5cbjx0ZW1wbGF0ZT5cbiAgPGRpdiBjbGFzcz1cImRlbW9cIj5cbiAgICA8bGFiZWw+PGlucHV0IHR5cGU9XCJyYWRpb1wiIHYtbW9kZWw9XCJjdXJyZW50XCIgOnZhbHVlPVwiQ29tcEFcIiAvPiBBPC9sYWJlbD5cbiAgICA8bGFiZWw+PGlucHV0IHR5cGU9XCJyYWRpb1wiIHYtbW9kZWw9XCJjdXJyZW50XCIgOnZhbHVlPVwiQ29tcEJcIiAvPiBCPC9sYWJlbD5cbiAgICA8S2VlcEFsaXZlPlxuICAgICAgPGNvbXBvbmVudCA6aXM9XCJjdXJyZW50XCI+PC9jb21wb25lbnQ+XG4gICAgPC9LZWVwQWxpdmU+XG4gIDwvZGl2PlxuPC90ZW1wbGF0ZT5cbiIsImltcG9ydC1tYXAuanNvbiI6IntcbiAgXCJpbXBvcnRzXCI6IHtcbiAgICBcInZ1ZVwiOiBcImh0dHBzOi8vc2ZjLnZ1ZWpzLm9yZy92dWUucnVudGltZS5lc20tYnJvd3Nlci5qc1wiXG4gIH1cbn0iLCJDb21wQS52dWUiOiI8c2NyaXB0IHNldHVwPlxuaW1wb3J0IHsgcmVmIH0gZnJvbSAndnVlJ1xuXG5jb25zdCBjb3VudCA9IHJlZigwKVxuPC9zY3JpcHQ+XG5cbjx0ZW1wbGF0ZT5cbiAgPHA+Q3VycmVudCBjb21wb25lbnQ6IEE8L3A+XG4gIDxzcGFuPmNvdW50OiB7eyBjb3VudCB9fTwvc3Bhbj5cbiAgPGJ1dHRvbiBAY2xpY2s9XCJjb3VudCsrXCI+KzwvYnV0dG9uPlxuPC90ZW1wbGF0ZT5cbiIsIkNvbXBCLnZ1ZSI6IjxzY3JpcHQgc2V0dXA+XG5pbXBvcnQgeyByZWYgfSBmcm9tICd2dWUnXG5jb25zdCBtc2cgPSByZWYoJycpXG48L3NjcmlwdD5cblxuPHRlbXBsYXRlPlxuICA8cD5DdXJyZW50IGNvbXBvbmVudDogQjwvcD5cbiAgPHNwYW4+TWVzc2FnZSBpczoge3sgbXNnIH19PC9zcGFuPlxuICA8aW5wdXQgdi1tb2RlbD1cIm1zZ1wiPlxuPC90ZW1wbGF0ZT5cbiJ9)
+
+</div>
+<div class="options-api">
+
+[Try it in the Playground](https://sfc.vuejs.org/#eyJBcHAudnVlIjoiPHNjcmlwdD5cbmltcG9ydCBDb21wQSBmcm9tICcuL0NvbXBBLnZ1ZSdcbmltcG9ydCBDb21wQiBmcm9tICcuL0NvbXBCLnZ1ZSdcbiAgXG5leHBvcnQgZGVmYXVsdCB7XG4gIGNvbXBvbmVudHM6IHsgQ29tcEEsIENvbXBCIH0sXG4gIGRhdGEoKSB7XG4gICAgcmV0dXJuIHtcbiAgICAgIGN1cnJlbnQ6ICdDb21wQSdcbiAgICB9XG4gIH1cbn1cbjwvc2NyaXB0PlxuXG48dGVtcGxhdGU+XG4gIDxkaXYgY2xhc3M9XCJkZW1vXCI+XG4gICAgPGxhYmVsPjxpbnB1dCB0eXBlPVwicmFkaW9cIiB2LW1vZGVsPVwiY3VycmVudFwiIHZhbHVlPVwiQ29tcEFcIiAvPiBBPC9sYWJlbD5cbiAgICA8bGFiZWw+PGlucHV0IHR5cGU9XCJyYWRpb1wiIHYtbW9kZWw9XCJjdXJyZW50XCIgdmFsdWU9XCJDb21wQlwiIC8+IEI8L2xhYmVsPlxuICAgIDxLZWVwQWxpdmU+XG4gICAgICA8Y29tcG9uZW50IDppcz1cImN1cnJlbnRcIj48L2NvbXBvbmVudD5cbiAgICA8L0tlZXBBbGl2ZT5cbiAgPC9kaXY+XG48L3RlbXBsYXRlPlxuIiwiaW1wb3J0LW1hcC5qc29uIjoie1xuICBcImltcG9ydHNcIjoge1xuICAgIFwidnVlXCI6IFwiaHR0cHM6Ly9zZmMudnVlanMub3JnL3Z1ZS5ydW50aW1lLmVzbS1icm93c2VyLmpzXCJcbiAgfVxufSIsIkNvbXBBLnZ1ZSI6IjxzY3JpcHQ+XG5leHBvcnQgZGVmYXVsdCB7XG4gIGRhdGEoKSB7XG4gICAgcmV0dXJuIHtcbiAgICAgIGNvdW50OiAwXG4gICAgfVxuICB9XG59XG48L3NjcmlwdD5cblxuPHRlbXBsYXRlPlxuICA8cD5DdXJyZW50IGNvbXBvbmVudDogQTwvcD5cbiAgPHNwYW4+Y291bnQ6IHt7IGNvdW50IH19PC9zcGFuPlxuICA8YnV0dG9uIEBjbGljaz1cImNvdW50KytcIj4rPC9idXR0b24+XG48L3RlbXBsYXRlPlxuIiwiQ29tcEIudnVlIjoiPHNjcmlwdD5cbmV4cG9ydCBkZWZhdWx0IHtcbiAgZGF0YSgpIHtcbiAgICByZXR1cm4ge1xuICAgICAgbXNnOiAnJ1xuICAgIH1cbiAgfVxufVxuPC9zY3JpcHQ+XG5cblxuPHRlbXBsYXRlPlxuICA8cD5DdXJyZW50IGNvbXBvbmVudDogQjwvcD5cbiAgPHNwYW4+TWVzc2FnZSBpczoge3sgbXNnIH19PC9zcGFuPlxuICA8aW5wdXQgdi1tb2RlbD1cIm1zZ1wiPlxuPC90ZW1wbGF0ZT5cbiJ9)
+
+</div>
+
+:::tip
+When used in [DOM templates](/guide/essentials/component-basics.html#dom-template-parsing-caveats), it should be referenced as `<keep-alive>`.
+:::
 
 ## Include / Exclude
 
+By default, `<KeepAlive>` will cache any component instance inside. We can customize this behavior via the `include` and `exclude` props. Both props can be a comma-delimited string, a `RegExp`, or an array containing either types:
+
+```vue-html
+<!-- comma-delimited string -->
+<KeepAlive include="a,b">
+  <component :is="view"></component>
+</KeepAlive>
+
+<!-- regex (use `v-bind`) -->
+<KeepAlive :include="/a|b/">
+  <component :is="view"></component>
+</KeepAlive>
+
+<!-- Array (use `v-bind`) -->
+<KeepAlive :include="['a', 'b']">
+  <component :is="view"></component>
+</KeepAlive>
+```
+
+The match is checked against the component's [`name`](/api/options-misc.html#name) option, so components that need to be conditionally cached by `KeepAlive` must explicitly delcare a `name` option.
+
 ## Max Cached Instances
+
+We can limit the maximum number of component instances that can be cached via the `max` prop. When `max` is specified, `<KeepAlive>` behaves like an [LRU cache](<https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)>): if the number of cached instances is about to exceed the specified max count, the least recently accessed cached instance will be destroyed to make room for the new one.
+
+```vue-html
+<KeepAlive :max="10">
+  <component :is="activeComponent" />
+</KeepAlive>
+```

src/guide/built-ins/suspense.md

@@ -1,4 +1,4 @@
-# Suspense
+# Suspense <Badge type="warning" text="experimental" />
 
 ## Basic Usage
 

src/guide/extras/reactivity-in-depth.md

@@ -2,7 +2,7 @@
 aside: deep
 ---
 
-# Reactivity in Depth
+# Reactivity in Depth <Badge text="WIP" />
 
 // TODO explain proxies
 // TODO explain refs

src/guide/extras/render-function.md

@@ -1,4 +1,4 @@
-# Render Functions
+# Render Functions <Badge text="WIP" />
 
 Vue recommends using templates to build applications in the vast majority of cases. However, there are situations where we need the full programmatic power of JavaScript. That's where we can use the **render function**.
 

src/guide/extras/rendering-mechanism.md

@@ -1,17 +1 @@
-# Rendering Mechanism
-
-> This page is not required reading in order to learn how to use Vue well, but it provides more information, should you be curious how rendering works under the hood.
-
-## Virtual DOM
-
-Now that we know how watchers are updating the components, you might ask how those changes eventually make it to the DOM! Perhaps you’ve heard of the Virtual DOM before, many frameworks including Vue use this paradigm to make sure our interfaces reflect the changes we’re updating in JavaScript effectively
-
-<div class="reactivecontent">
-  <!-- <common-codepen-snippet title="How does the Virtual DOM work?" slug="KKNJKbw" tab="result" theme="light" :height="500" :editable="false" :preview="false" /> -->
-</div>
-
-We make a copy of the DOM in JavaScript called the Virtual DOM, we do this because touching the DOM with JavaScript is computationally expensive. While performing updates in JavaScript is cheap, finding the required DOM nodes and updating them with JavaScript is expensive. So we batch calls, and change the DOM all at once.
-
-The Virtual DOM is a lightweight JavaScript object, created by a render function. It takes three arguments: the element, an object with data, props, attrs and more, and an array. The array is where we pass in the children, which have all these arguments too, and then they can have children and so on, until we build a full tree of elements.
-
-If we need to update the list items, we do so in JavaScript, using the reactivity we mentioned earlier. We then make all the changes to the JavaScript copy, the virtual DOM, and perform a diff between this and the actual DOM. Only then do we make our updates to just what has changed. The Virtual DOM allows us to make performant updates to our UIs!
+# Rendering Mechanism <Badge text="WIP" />