split reactivity transform into dedicated page

Author: yyx990803

src/.vitepress/config.ts

@@ -256,6 +256,10 @@ export const sidebar = {
         {
           text: 'Animation Techniques',
           link: '/guide/extras/animation'
+        },
+        {
+          text: 'Reactivity Transform',
+          link: '/guide/extras/reactivity-transform'
         }
         // {
         //   text: 'Building a Library for Vue',

src/.vitepress/theme/index.ts

@@ -6,6 +6,7 @@ import {
   preferSFC,
   filterHeadersByPreference
 } from './components/preferences'
+import './styles/badges.css'
 import './styles/utilities.css'
 import './styles/inline-demo.css'
 import './styles/options-boxes.css'

src/.vitepress/theme/styles/badges.css

@@ -0,0 +1,3 @@
+.vt-badge.ts {
+  background-color: #3178c6;
+}

src/guide/essentials/reactivity-fundamentals.md

@@ -520,15 +520,16 @@ app.component('save-button', {
 
 <div class="composition-api">
 
-### Reactivity Transform <Badge type="warning" text="experimental" /> \*\*
+## Reactivity Transform <Badge type="warning" text="experimental" /> \*\*
 
-Having to use `.value` with refs is a drawback imposed by the language constraints of JavaScript. However, with compile-time transforms we can improve the ergonomics by automatically appending `.value` in appropriate locations. [Vue Reactivity Transform](https://github.com/vuejs/vue-next/tree/master/packages/reactivity-transform) allows us to write the above example like this:
+Having to use `.value` with refs is a drawback imposed by the language constraints of JavaScript. However, with compile-time transforms we can improve the ergonomics by automatically appending `.value` in appropriate locations. Vue provides a compile-time transform that allows us to write the ealier "counter" example like this:
 
 ```vue
 <script setup>
 let count = $ref(0)
 
 function increment() {
+  // no need for .value
   count++
 }
 </script>
@@ -538,8 +539,6 @@ function increment() {
 </template>
 ```
 
-:::warning Experimental Feature
-Reactivity transform is currently an experimental feature. It is disabled by default and requires [explicit opt-in](https://github.com/vuejs/rfcs/blob/reactivity-transform/active-rfcs/0000-reactivity-transform.md#enabling-the-macros). It may also change before being finalized. More details can be found in its [proposal and discussion on GitHub](https://github.com/vuejs/rfcs/discussions/369).
-:::
+You can learn more about [Reactivity Transform](/guide/extras/reactivity-transform.html) in its dedicated section. Do note that it is currently still experimental and may change before being finalized.
 
 </div>

src/guide/extras/reactivity-transform.md

@@ -0,0 +1,345 @@
+# Reactivity Transform
+
+:::warning Experimental Feature
+Reactivity Transform is currently an experimental feature. It is disabled by default and requires [explicit opt-in](#explicit-opt-in). It may also change before being finalized. To stay up-to-date, keep an eye on its [proposal and discussion on GitHub](https://github.com/vuejs/rfcs/discussions/369).
+:::
+
+:::tip Composition-API-specific
+Reactivity Transform is a Composition-API-specific feature and requires a build step.
+:::
+
+## Refs vs. Reactive Variables
+
+Ever since the introduction of the Composition API, one of the primary unresolved questions is the use of refs vs. reactive objects. It can be cumbersome to use `.value` everywhere, and it is easy to miss if not using a type system.
+
+[Vue Reactivity Transform](https://github.com/vuejs/vue-next/tree/master/packages/reactivity-transform) is a compile-time transform that allows us to write code like this:
+
+```vue
+<script setup>
+let count = $ref(0)
+
+console.log(count)
+
+function increment() {
+  count++
+}
+</script>
+
+<template>
+  <button @click="increment">{{ count }}</button>
+</template>
+```
+
+The `$ref()` method here is a **compile-time macro**: it is not an actual method that will be called at runtime. Instead, the Vue compiler uses it as a hint to treat the resulting `count` variable as a **reactive variable.**
+
+Reactive variables can be accessed and re-assigned just like normal variables, but these operations are compiled into refs with `.value`. For example, the `<script>` part of the above component is compiled into:
+
+```js{5,8}
+import { ref } from 'vue'
+
+let count = ref(0)
+
+console.log(count.value)
+
+function increment() {
+  count.value++
+}
+```
+
+Every reactivity API that returns refs will have a `$`-prefixed macro equivalent. These APIs include:
+
+- [`ref`](/api/reactivity-core.html#ref) -> `$ref`
+- [`computed`](/api/reactivity-core.html#computed) -> `$computed`
+- [`shallowRef`](/api/reactivity-advanced.html#shallowref) -> `$shallowRef`
+- [`customRef`](/api/reactivity-advanced.html#customref) -> `$customRef`
+- [`toRef`](/api/reactivity-utilities.html#toref) -> `$toRef`
+
+These macros are globally available and do not need to be imported when Reactivity Transform is enabled, but you can optionally import them from `vue/macros` if you want to be more explicit:
+
+```js
+import { $ref } from 'vue/macros'
+
+let count = $ref(0)
+```
+
+## Destructuring with `$()`
+
+It is common for a composition function to return an object of refs, and use destructuring to retrieve these refs. For this purpose, reactivity transform provides the **`$()`** macro:
+
+```js
+import { useMouse } from '@vueuse/core'
+
+const { x, y } = $(useMouse())
+
+console.log(x, y)
+```
+
+Compiled output:
+
+```js
+import { toRef } from 'vue'
+import { useMouse } from '@vueuse/core'
+
+const __temp = useMouse(),
+  x = toRef(__temp, 'x'),
+  y = toRef(__temp, 'y')
+
+console.log(x.value, y.value)
+```
+
+Note that if `x` is already a ref, `toRef(__temp, 'x')` will simply return it as-is and no additional ref will be created. If a destructured value is not a ref (e.g. a function), it will still work - the value will be wrapped into a ref so the rest of the code work as expected.
+
+`$()` destructure works on both reactive objects **and** plain objects containing refs.
+
+## Convert Existing Refs to Reactive Variables with `$()`
+
+In some cases we may have wrapped functions that also return refs. However, the Vue compiler won't be able to know ahead of time that a function is going to return a ref. In such cases, the `$()` macro can also be used to convert any existing refs into reactive variables:
+
+```js
+function myCreateRef() {
+  return ref(0)
+}
+
+let count = $(myCreateRef())
+```
+
+## Reactive Props Destructure
+
+There are two pain points with the current `defineProps()` usage in `<script setup>`:
+
+1. Similar to `.value`, you need to always access props as `props.x` in order to retain reactivity. This means you cannot destructure `defineProps` because the resulting destructured variables are not reactive and will not update.
+
+2. When using the [type-only props declaration](https://v3.vuejs.org/api/sfc-script-setup.html#typescript-only-features), there is no easy way to declare default values for the props. We introduced the `withDefaults()` API for this exact purpose, but it's still clunky to use.
+
+We can address these issues by applying the same logic for reactive variables destructure to `defineProps`:
+
+```html
+<script setup lang="ts">
+  interface Props {
+    msg: string
+    count?: number
+    foo?: string
+  }
+
+  const {
+    msg,
+    // default value just works
+    count = 1,
+    // local aliasing also just works
+    // here we are aliasing `props.foo` to `bar`
+    foo: bar
+  } = defineProps<Props>()
+
+  watchEffect(() => {
+    // will log whenever the props change
+    console.log(msg, count, bar)
+  })
+</script>
+```
+
+the above will be compiled into the following runtime declaration equivalent:
+
+```js
+export default {
+  props: {
+    msg: { type: String, required: true },
+    count: { type: Number, default: 1 },
+    foo: String
+  },
+  setup(props) {
+    watchEffect(() => {
+      console.log(props.msg, props.count, props.foo)
+    })
+  }
+}
+```
+
+## Retaining Reactivity Across Function Boundaries
+
+While reactive variables relieve us from having to use `.value` everywhere, it creates an issue of "reactivity loss" when we pass reactive variables across function boundaries. This can happen in two cases:
+
+### Passing into function as argument
+
+Given a function that expects a ref object as argument, e.g.:
+
+```ts
+function trackChange(x: Ref<number>) {
+  watch(x, (x) => {
+    console.log('x changed!')
+  })
+}
+
+let count = $ref(0)
+trackChange(count) // doesn't work!
+```
+
+The above case will not work as expected because it compiles to:
+
+```ts
+let count = ref(0)
+trackChange(count.value)
+```
+
+Here `count.value` is passed as a number where `trackChange` expects an actual ref. This can be fixed by wrapping `count` with `$$()` before passing it:
+
+```diff
+let count = $ref(0)
+- trackChange(count)
++ trackChange($$(count))
+```
+
+The above compiles to:
+
+```js
+import { ref } from 'vue'
+
+let count = ref(0)
+trackChange(count)
+```
+
+As we can see, `$$()` is a macro that serves as an **escape hint**: reactive variables inside `$$()` will not get `.value` appended.
+
+### Returning inside function scope
+
+Reactivity can also be lost if reactive variables are used directly in a returned expression:
+
+```ts
+function useMouse() {
+  let x = $ref(0)
+  let y = $ref(0)
+
+  // listen to mousemove...
+
+  // doesn't work!
+  return {
+    x,
+    y
+  }
+}
+```
+
+The above return statement compiles to:
+
+```ts
+return {
+  x: x.value,
+  y: y.value
+}
+```
+
+In order to retain reactivity, we should be returning the actual refs, not the current value at return time.
+
+Again, we can use `$$()` to fix this. In this case, `$$()` can be used directly on the returned object - any reference to reactive variables inside the `$$()` call will be retained as reference to their underlying refs:
+
+```ts
+function useMouse() {
+  let x = $ref(0)
+  let y = $ref(0)
+
+  // listen to mousemove...
+
+  // fixed
+  return $$({
+    x,
+    y
+  })
+}
+```
+
+### `$$()` Usage on destructured props
+
+`$$()` works on destructured props since they are reactive variables as well. The compiler will convert it with `toRef` for efficiency:
+
+```ts
+const { count } = defineProps<{ count: number }>()
+
+passAsRef($$(count))
+```
+
+compiles to:
+
+```js
+setup(props) {
+  const __props_count = toRef(props, 'count')
+  passAsRef(__props_count)
+}
+```
+
+## TypeScript Integration <Badge type="ts" text="TS" />
+
+Vue provides typings for these macros (available globally) and all types will work as expected. There are no incompatibilities with standard TypeScript semantics so the syntax would work with all existing tooling.
+
+This also means the macros can work in any files where valid JS / TS are allowed - not just inside Vue SFCs.
+
+Since the macros are available globally, their types need to be explicitly referenced (e.g. in a `env.d.ts` file):
+
+```ts
+/// <reference types="vue/macros-global" />
+```
+
+When explicitly importing the macros from `vue/macros`, the type will work without declaring the globals.
+
+## Explicit Opt-in
+
+Reactivity Transform is currently disabled by default and requires explicit opt-in. In addition, all of the following setups require `vue@^3.2.25`.
+
+### Vite
+
+- Requires `@vitejs/plugin-vue@^2.0.0`
+- Applies to SFCs and js(x)/ts(x) files. A fast usage check is performed on files before applying the transform so there should be no performance cost for files not using the macros.
+- Note `refTransform` is now a plugin root-level option instead of nested as `script.refSugar`, since it affects not just SFCs.
+
+```js
+// vite.config.js
+export default {
+  plugins: [
+    vue({
+      reactivityTransform: true
+    })
+  ]
+}
+```
+
+### `vue-cli`
+
+- Currently only affects SFCs
+- requires `vue-loader@^17.0.0`
+
+```js
+// vue.config.js
+module.exports = {
+  chainWebpack: (config) => {
+    config.module
+      .rule('vue')
+      .use('vue-loader')
+      .tap((options) => {
+        return {
+          ...options,
+          reactivityTransform: true
+        }
+      })
+  }
+}
+```
+
+### Plain `webpack` + `vue-loader`
+
+- Currently only affects SFCs
+- requires `vue-loader@^17.0.0`
+
+```js
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.vue$/,
+        loader: 'vue-loader',
+        options: {
+          reactivityTransform: true
+        }
+      }
+    ]
+  }
+}
+```