docs: add single define docs (#318)

zzhenryquezz · sxzz · web-flow · commit 53203a2f7097 · 2023-03-22T18:50:20.000Z
* fix(macros): missing single-define ts types

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

* refactor(docs): merge defineEmit &amp; defineProp page

* docs: update

* chore: add changesets file

---------

Co-authored-by: 三咲智子 Kevin Deng &lt;sxzz@sxzz.moe&gt;
diff --git a/.changeset/spicy-donuts-raise.md b/.changeset/spicy-donuts-raise.md
@@ -0,0 +1,5 @@
+---
+'unplugin-vue-macros': minor
+---
+
+introduce `singleDefine`
diff --git a/docs/.vitepress/locales/common.ts b/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`,
+        },
       ],
     },
     {
diff --git a/docs/macros/index.md b/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>
diff --git a/docs/macros/single-define.md b/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>
+```
diff --git a/docs/zh-CN/macros/single-define.md b/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>
+```
diff --git a/packages/macros/macros-global.d.ts b/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 {}
diff --git a/packages/macros/macros.d.ts b/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'

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'unplugin-vue-macros': minor
 +---
++
 +introduce `singleDefine`