docs: add single define docs (#318)

* fix(macros): missing single-define ts types

* feat(docs): add single-define macors docs

* refactor(docs): merge defineEmit & defineProp page

* docs: update

* chore: add changesets file

---------

Co-authored-by: 三咲智子 Kevin Deng <sxzz@sxzz.moe>

.changeset/spicy-donuts-raise.md

@@ -0,0 +1,5 @@
+---
+'unplugin-vue-macros': minor
+---
+
+introduce `singleDefine`

docs/.vitepress/locales/common.ts

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

docs/macros/index.md

@@ -14,3 +14,4 @@ Please make sure `unplugin-vue-macros` is set up correctly. If you haven't yet,
 - [shortVmodel](/macros/short-vmodel)
 - [setupComponent](/macros/setup-component) <WarnBadge>Experimental</WarnBadge>
 - [setupSFC](/macros/setup-sfc) <WarnBadge>Experimental</WarnBadge>
+- [singleDefine](/macros/single-define)<WarnBadge>unstable</WarnBadge>

docs/macros/single-define.md

@@ -0,0 +1,81 @@
+# singleDefine
+
+<small>Stability: <code class="!text-yellow-600">unstable</code></small>
+
+Declare single props and events with `defineProp` & `defineEmit`.
+
+|  Features  |     Supported      |
+| :--------: | :----------------: |
+|   Vue 3    | :white_check_mark: |
+|   Nuxt 3   | :white_check_mark: |
+|   Vue 2    | :white_check_mark: |
+| TypeScript | :white_check_mark: |
+
+::: warning
+
+`defineProp` can not be used with `defineProps` at same time
+
+`defineEmit` can not be used with `defineEmits` at same time
+
+:::
+
+## Basic Usage
+
+```vue
+<script setup>
+// Declare prop
+const count = defineProp('count')
+// Declare event
+const increment = defineEmit('increment')
+
+// access prop value
+console.log(count.value)
+// emit event
+increment()
+</script>
+```
+
+## With Options & Validation
+
+```vue
+<script setup>
+// Declare prop with options
+const count = defineProp('count', {
+  type: Number,
+  required: true,
+  default: 0,
+  validator: (value) => value < 20,
+})
+
+// Declare event with validation
+const increment = defineEmit('increment', (value) => value < 20)
+</script>
+```
+
+## Using Multiple Times
+
+```vue
+<script setup>
+const count = defineProp('count')
+const maxCount = defineProp('maxCount')
+const increment = defineEmit('increment')
+const decrement = defineEmit('decrement')
+</script>
+```
+
+## TypeScript
+
+```vue
+<script setup lang="ts">
+// Declare prop of type number
+const count = defineProp<number>('count')
+
+count.value
+//    ^ type number
+
+const increment = defineEmit('bar', (value: number) => value < 20)
+
+increment(2) // pass
+increment('2') // TS type error
+</script>
+```

docs/zh-CN/macros/single-define.md

@@ -0,0 +1,81 @@
+# singleDefine
+
+<small>Stability: <code class="!text-yellow-600">unstable</code></small>
+
+Declare single props and events with `defineProp` & `defineEmit`.
+
+|  Features  |     Supported      |
+| :--------: | :----------------: |
+|   Vue 3    | :white_check_mark: |
+|   Nuxt 3   | :white_check_mark: |
+|   Vue 2    | :white_check_mark: |
+| TypeScript | :white_check_mark: |
+
+::: warning
+
+`defineProp` can not be used with `defineProps` at same time
+
+`defineEmit` can not be used with `defineEmits` at same time
+
+:::
+
+## Basic Usage
+
+```vue
+<script setup>
+// Declare prop
+const count = defineProp('count')
+// Declare event
+const increment = defineEmit('increment')
+
+// access prop value
+console.log(count.value)
+// emit event
+increment()
+</script>
+```
+
+## With Options & Validation
+
+```vue
+<script setup>
+// Declare prop with options
+const count = defineProp('count', {
+  type: Number,
+  required: true,
+  default: 0,
+  validator: (value) => value < 20,
+})
+
+// Declare event with validation
+const increment = defineEmit('increment', (value) => value < 20)
+</script>
+```
+
+## Using Multiple Times
+
+```vue
+<script setup>
+const count = defineProp('count')
+const maxCount = defineProp('maxCount')
+const increment = defineEmit('increment')
+const decrement = defineEmit('decrement')
+</script>
+```
+
+## TypeScript
+
+```vue
+<script setup lang="ts">
+// Declare prop of type number
+const count = defineProp<number>('count')
+
+count.value
+//    ^ type number
+
+const increment = defineEmit('bar', (value: number) => value < 20)
+
+increment(2) // pass
+increment('2') // TS type error
+</script>
+```

packages/macros/macros-global.d.ts

@@ -7,5 +7,6 @@
 /// <reference types="@vue-macros/reactivity-transform/macros-global" />
 /// <reference types="@vue-macros/setup-component/macros-global" />
 /// <reference types="@vue-macros/short-emits/macros-global" />
+/// <reference types="@vue-macros/single-define/macros-global" />
 
 export {}

packages/macros/macros.d.ts

@@ -7,3 +7,4 @@ export * from '@vue-macros/define-slots/macros'
 export * from '@vue-macros/reactivity-transform/macros'
 export * from '@vue-macros/setup-component/macros'
 export * from '@vue-macros/short-emits/macros'
+export * from '@vue-macros/single-define/macros'