docs: update

Author: zhiyuanzmj

docs/.vitepress/config.ts

@@ -57,6 +57,7 @@ export default defineConfig({
     ],
   },
   markdown: {
+    languages: ['js', 'ts'],
     codeTransformers: [
       transformerTwoslash({
         twoslasher: createTwoslasher({

docs/features/directives.md

@@ -11,6 +11,22 @@ Vue built-in directives for JSX.
 |           `v-html`            | :white_check_mark: |         /          |
 |           `v-once`            | :white_check_mark: |         /          |
 
+## Dynamic Arguments
+
+It is also possible to use a variable in a directive argument.
+Because JSX doesn't support `[]` keyword, use `$` instead.
+
+## Modifiers
+
+Modifiers are special postfixes denoted by a `_`, which indicate that a directive should be bound in some special way.
+Because JSX doesn't support `.` keyword, we use `_` instead.
+
+```tsx
+<form onSubmit_prevent>
+  <input v-model_number={value} />
+</form>
+```
+
 ## `v-if`, `v-else-if`, `v-else`
 
 ```tsx twoslash
@@ -80,27 +96,21 @@ const Comp = () => {
   return <div />
 }
 
-// ---cut-start---
-// prettier-ignore
-// ---cut-end---
 export default () => (
-  <Comp v-slots={{
-    default: () => <>default slot</>,
-    slot: ({ bar }) => <>{bar}</>
-  }} />
+  <Comp
+    v-slots={{
+      default: () => <>default slot</>,
+      slot: ({ bar }) => <>{bar}</>,
+    }}
+  />
 )
 ```
 
 :::
 
-## Dynamic Arguments
-
-It is also possible to use a variable in a directive argument.
-Because JSX doesn't support `[]` keyword, use `$` instead.
-
-### `v-model`
+## `v-model`
 
-```tsx
+```tsx twoslash
 import { ref } from 'vue'
 
 const Comp = () => {
@@ -122,7 +132,7 @@ export default () => {
 }
 ```
 
-### `v-slot`
+## `v-slot`
 
 ```tsx twoslash
 export const Comp = () => {
@@ -150,14 +160,3 @@ export default () => (
   </Comp>
 )
 ```
-
-## Modifiers
-
-Modifiers are special postfixes denoted by a `_`, which indicate that a directive should be bound in some special way. 
-Because JSX doesn't support `.` keyword, we use `_` instead.
-
-```tsx
-<form onSubmit_prevent>
-  <input v-model_number={value} />
-</form>
-```

docs/features/macros.md

@@ -1,7 +1,5 @@
 # Macros
 
-<StabilityLevel level="experimental" />
-
 A collection of macros. They are need to muanually enabled by set `macros` to `true`.
 
 |     Directive     |        Vue         |       Volar        |
@@ -16,7 +14,7 @@ A collection of macros. They are need to muanually enabled by set `macros` to `t
 
 ::: code-group
 
-```ts {6} [vite.config.ts]
+```ts {7} [vite.config.ts]
 import { defineConfig } from 'vite'
 import vueJsxVapor from 'vue-jsx-vapor/vite'
 
@@ -29,7 +27,7 @@ export default defineConfig({
 })
 ```
 
-```ts {5} [tsm.config.ts]
+```ts {6} [tsm.config.ts]
 import vueJsxVapor from 'vue-jsx-vapor/volar'
 
 export default {
@@ -145,18 +143,19 @@ defineComponent(
 - Will be inferred as a required prop when the expression ends with `!`.
 - The modified model's value can be read synchronously, without needing to `await nextTick()`. [Related issue](https://github.com/vuejs/core/issues/11080)
 
-```tsx
+```tsx twoslash
 import { ref } from 'vue'
 
 function Comp() {
   const modelValue = defineModel<string>()!
   modelValue.value = 'foo'
   return <div>{modelValue.value}</div>
+  //                      ^?
 }
 
 export default () => {
   const foo = ref('')
-  return <Comp v-model={foo.value} />
+  return <input value={foo.value} />
 }
 ```
 
@@ -208,11 +207,14 @@ function Comp<const T>() {
   )
 }
 
+// ---cut-start---
+// prettier-ignore
+// ---cut-end---
 export default () => (
   <Comp<1>>
     <template v-slot={{ foo }}>{foo}</template>
     <template v-slot:title={{ bar }}>{bar}</template>
-    // ^?
+    //                        ^?
   </Comp>
 )
 ```
@@ -221,7 +223,7 @@ export default () => (
 
 Just like in Vue SFC.
 
-```tsx
+```tsx twoslash
 import { useRef } from 'vue-jsx-vapor'
 
 const Comp = <T,>({ foo = undefined as T }) => {
@@ -234,7 +236,7 @@ const Comp = <T,>({ foo = undefined as T }) => {
 export default () => {
   const compRef = useRef()
   compRef.value?.foo
-  //              ^?
+  //             ^?
 
   return <Comp ref={compRef} foo={1 as const} />
 }
@@ -313,6 +315,7 @@ export default () => {
       }
     }
   `)
+
   return <div class={styles.bar} />
   //                         ^?
 }

docs/features/use-ref.md

@@ -4,12 +4,11 @@ Automatically infer type for `useRef`. It's an alias of `shallowRef`.
 
 ## Basic Usage
 
-::: code-group
-
-```tsx
-import { defineComponent, shallowRef as useRef } from 'vue'
+```tsx twoslash
+import { defineComponent } from 'vue'
+import { useRef } from 'vue-jsx-vapor'
 // or
-// import { useRef } from 'vue-jsx-vapor'
+// import { shallowRef as useRef } from 'vue'
 
 export const Comp = defineComponent({
   setup() {

docs/introduction/migration.md

@@ -4,4 +4,71 @@
 
 1. Doesn't support hyphenated prop name and hyphenated component name.
 2. `v-model` doesn't support Array Expression, use `v-model:$name$_trim={foo}` instead.
-3. Doesn't support `v-models` directive.
+3. Doesn't support `v-models` directive.
+4. Destructing props:
+
+> [!CAUTION]
+> ❌ The destructuring of props in a functional component will cause loss of reactivity.
+
+```tsx
+function Comp({ foo }) {
+  return <div>{foo}</div>
+}
+
+export default () => {
+  const foo = ref('foo')
+  return <Comp foo={foo.value} />
+}
+```
+
+#### Two Solutions
+
+1. ✅ Pass a ref variable as prop:
+
+```tsx
+function Comp({ foo }) {
+  return <div>{foo.value}</div>
+}
+
+export default () => {
+  const foo = ref('foo')
+  return <Comp foo={foo} />
+}
+```
+
+2. ✅ Set the macros option to true, then use the `defineComponent` macro for wrapping.
+
+  - Setup
+
+    ```ts {7}
+    // vite.config.ts
+    import vueJsxVapor from 'vue-jsx-vapor/vite'
+
+    export default defineConfig({
+      plugins: [
+        vueJsxVapor({
+          macros: true,
+        }),
+      ]
+    })
+
+    ```
+
+  - Usage
+
+    ```tsx
+    import { defineComponent, ref } from 'vue'
+
+    const Comp = defineComponent(({ foo }) => {
+      return <>{foo}</>
+    })
+    // Will be convert to:
+    const Comp = defineComponent((_props) => {
+      return <>{_props.foo}</>
+    }, { props: ['foo'] })
+
+    export default () => {
+      const foo = ref('foo')
+      return <Comp foo={foo.value} />
+    }
+    ```