docs: add chain-call (#393)

Co-authored-by: 三咲智子 Kevin Deng <[email protected]>

Author: alexzhang1030

docs/.vitepress/locales/common.ts

@@ -123,6 +123,10 @@ export const sidebar = (lang: string): DefaultTheme.SidebarItem[] => {
               text: 'setupSFC',
               link: `${urlPrefix}/macros/setup-sfc`,
             },
+            {
+              text: 'chainCall',
+              link: `${urlPrefix}/macros/chain-call`,
+            },
           ],
         },
       ],

docs/features/export-props.md

@@ -7,8 +7,8 @@
 |   Features   |     Supported      |
 | :----------: | :----------------: |
 |    Vue 3     | :white_check_mark: |
-|    Nuxt 3    |         ?          |
-|    Vue 2     |         ?          |
+|    Nuxt 3    |     :question:     |
+|    Vue 2     |     :question:     |
 | Volar Plugin | :white_check_mark: |
 
 ## Usage

docs/macros/chain-call.md

@@ -0,0 +1,93 @@
+# chainCall
+
+<StabilityLevel level="experimental" />
+
+Extends `defineProps`, support call `withDefaults` as a chain.
+
+|   Features   |     Supported      |
+| :----------: | :----------------: |
+|    Vue 3     | :white_check_mark: |
+|    Nuxt 3    |     :question:     |
+|    Vue 2     |     :question:     |
+|  TypeScript  | :white_check_mark: |
+| Volar Plugin |        :x:         |
+
+::: tip
+
+- `chainCall` does not support `definePropsRefs`
+- To fully support TypeScript, you need to import this macro from `unplugin-vue-macros/macros`.
+
+:::
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{
+  foo?: string
+  bar?: number[]
+  baz?: boolean
+}>().withDefaults({
+  foo: '111',
+  bar: () => [1, 2, 3],
+})
+</script>
+```
+
+::: details Compiled Code
+
+```vue
+<script setup lang="ts">
+const props = withDefaults(
+  defineProps<{
+    foo?: string
+    bar?: number[]
+    baz?: boolean
+  }>(),
+  {
+    foo: '111',
+    bar: () => [1, 2, 3],
+  }
+)
+</script>
+```
+
+:::
+
+Also support [props destructuring](/features/reactivity-transform.html) and JSX:
+
+```vue
+<script setup lang="tsx">
+const { foo } = defineProps<{ foo: string }>().withDefaults({
+  foo: '111',
+})
+</script>
+```
+
+## TypeScript
+
+To fully support TypeScript, you need to import this macro from `unplugin-vue-macros/macros` with specific syntax.
+
+```vue
+<script setup lang="ts">
+import { defineProps } from 'unplugin-vue-macros/macros' assert { type: 'macro' }
+
+defineProps<{
+  /* ... */
+}>().withDefaults({
+  /* ... */
+})
+// ✅ type safe
+</script>
+```
+
+Works without import assertion, but tsc will report an error:
+
+```ts
+defineProps<{
+  /* ... */
+}>().withDefaults({
+  /* ... */
+})
+// ❌ Property 'withDefaults' does not exist on type 'DefineProps<{ /* ... */ }>'.
+```

docs/macros/index.md

@@ -24,3 +24,4 @@ Please make sure `unplugin-vue-macros` is set up correctly. If you haven't yet,
 - [defineEmit](/macros/define-emit)
 - [setupComponent](/macros/setup-component)
 - [setupSFC](/macros/setup-sfc)
+- [chainCall](/macros/chain-call)

docs/zh-CN/macros/chain-call.md

@@ -0,0 +1,93 @@
+# chainCall
+
+<StabilityLevel level="experimental" />
+
+扩展 `defineProps`，支持链式调用 `withDefaults`。
+
+|   Features   |     Supported      |
+| :----------: | :----------------: |
+|    Vue 3     | :white_check_mark: |
+|    Nuxt 3    |     :question:     |
+|    Vue 2     |     :question:     |
+|  TypeScript  | :white_check_mark: |
+| Volar Plugin |        :x:         |
+
+::: tip
+
+- `chainCall` 不支持 `definePropsRefs`。
+- 你需要从 `unplugin-vue-macros/macros` 中导入此宏以获取更好的类型检查。
+
+:::
+
+## 基本用法
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{
+  foo?: string
+  bar?: number[]
+  baz?: boolean
+}>().withDefaults({
+  foo: '111',
+  bar: () => [1, 2, 3],
+})
+</script>
+```
+
+::: details 编译后的代码
+
+```vue
+<script setup lang="ts">
+const props = withDefaults(
+  defineProps<{
+    foo?: string
+    bar?: number[]
+    baz?: boolean
+  }>(),
+  {
+    foo: '111',
+    bar: () => [1, 2, 3],
+  }
+)
+</script>
+```
+
+:::
+
+也支持 [props 解构](/features/reactivity-transform.html) 和 JSX：
+
+```vue
+<script setup lang="tsx">
+const { foo } = defineProps<{ foo: string }>().withDefaults({
+  foo: '111',
+})
+</script>
+```
+
+## TypeScript
+
+为了更好的类型支持，你需要使用特定的语法从 `unplugin-vue-macros/macros` 中导入此宏。
+
+```vue
+<script setup lang="ts">
+import { defineProps } from 'unplugin-vue-macros/macros' assert { type: 'macro' }
+
+defineProps<{
+  /* ... */
+}>().withDefaults({
+  /* ... */
+})
+// ✅ 类型安全
+</script>
+```
+
+没有 `import` 也可以正常使用，但 `tsc` 会报告一个类型错误：
+
+```ts
+defineProps<{
+  /* ... */
+}>().withDefaults({
+  /* ... */
+})
+// ❌ Property 'withDefaults' does not exist on type 'DefineProps<{ /* ... */ }>'.
+```

docs/zh-CN/macros/index.md

@@ -24,3 +24,4 @@
 - [defineEmit](/zh-CN/macros/define-emit)
 - [setupComponent](/zh-CN/macros/setup-component)
 - [setupSFC](/zh-CN/macros/setup-sfc)
+- [chainCall](/macros/chain-call)