refactor: separate defineProp and defineEmit

.changeset/shiny-eagles-exercise.md

@@ -0,0 +1,12 @@
+---
+'@vue-macros/define-emit': minor
+'@vue-macros/define-prop': minor
+'unplugin-vue-macros': minor
+'@vue-macros/nuxt': minor
+'@vue-macros/api': minor
+'@vue-macros/better-define': patch
+'@vue-macros/test-utils': patch
+'@vue-macros/common': patch
+---
+
+separate `defineProp` and `defineEmit`

.vscode/settings.json

@@ -13,7 +13,7 @@
   "unocss.root": ["./docs", "./packages/devtools/src/client"],
   "explorer.fileNesting.patterns": {
     "index.ts": "rollup.ts, vite.ts, webpack.ts, esbuild.ts",
-    "macros.d.ts": "macros-global.d.ts, vue2-macros.d.ts, vue2-macros-global.d.ts"
+    "macros.d.ts": "macros*.d.ts, vue2-macros*.d.ts"
   },
   "files.exclude": {
     "**/.turbo": true

docs/.vitepress/locales/common.ts

@@ -110,8 +110,12 @@ export const sidebar = (lang: string): DefaultTheme.SidebarItem[] => {
           text: 'Experimental',
           items: [
             {
-              text: 'singleDefine',
-              link: `${urlPrefix}/macros/single-define`,
+              text: 'defineProp',
+              link: `${urlPrefix}/macros/define-prop`,
+            },
+            {
+              text: 'defineEmit',
+              link: `${urlPrefix}/macros/define-emit`,
             },
             {
               text: 'setupComponent',

docs/macros/define-emit.md

@@ -0,0 +1,64 @@
+# defineEmit
+
+<StabilityLevel level="experimental" />
+
+Declare single emit one by one using `defineEmit`.
+
+|   Features   |     Supported      |
+| :----------: | :----------------: |
+|    Vue 3     | :white_check_mark: |
+|    Nuxt 3    | :white_check_mark: |
+|    Vue 2     | :white_check_mark: |
+|  TypeScript  | :white_check_mark: |
+| Volar Plugin |        :x:         |
+
+::: warning
+
+`defineEmit` can not be used with `defineEmits` at same time
+
+:::
+
+## API Reference
+
+```ts
+defineEmit<T>(emitName)
+defineEmit<T>(emitName, validator)
+
+// emitName parameter can be optional,
+// and will be inferred from variable name
+const emitName = defineEmit<T>()
+```
+
+## Basic Usage
+
+```vue
+<script setup>
+// Declare emit
+const increment = defineEmit('increment')
+// Infer emit name from variable name
+const change = defineEmit()
+// emit event
+increment()
+</script>
+```
+
+## With Validation
+
+```vue
+<script setup>
+// Declare event with validation
+const increment = defineEmit('increment', (value) => value < 20)
+</script>
+```
+
+## TypeScript
+
+```vue
+<script setup lang="ts">
+const increment = defineEmit('increment', (value: number) => value < 20)
+const decrement = defineEmit<[value: number]>()
+
+increment(2) // pass
+increment('2') // TS type error
+</script>
+```

docs/macros/define-prop.md

@@ -0,0 +1,141 @@
+# defineProp
+
+<StabilityLevel level="experimental" />
+
+Declare single prop one by one using `defineProp`.
+
+|      Features      |     Supported      |
+| :----------------: | :----------------: |
+|       Vue 3        | :white_check_mark: |
+|       Nuxt 3       | :white_check_mark: |
+|       Vue 2        | :white_check_mark: |
+| TypeScript / Volar | :white_check_mark: |
+
+::: warning
+
+`defineProp` can not be used in the same file as `defineProps`.
+
+:::
+
+## Kevin's Edition
+
+### API Reference
+
+```ts
+defineProp<T>(propName)
+defineProp<T>(propName, options)
+
+// propName parameter can be optional,
+// and will be inferred from variable name
+const propName = defineProp<T>()
+```
+
+### Basic Usage
+
+```vue
+<script setup>
+// Declare prop
+const count = defineProp('count')
+// Infer prop name from variable name
+const value = defineProp()
+// access prop value
+console.log(count.value)
+</script>
+```
+
+### With Options
+
+```vue
+<script setup>
+// Declare prop with options
+const count = defineProp('count', {
+  type: Number,
+  required: true,
+  default: 0,
+  validator: (value) => value < 20,
+})
+</script>
+```
+
+### TypeScript
+
+```vue
+<script setup lang="ts">
+// Declare prop of type number and infer prop name from variable name
+const count = defineProp<number>()
+count.value
+//    ^? type: number | undefined
+
+// Declare prop of TS type boolean with default value
+const disabled = defineProp<boolean>('disabled', { default: true })
+//    ^? type: boolean
+</script>
+```
+
+## Johnson's Proposal
+
+### API Reference
+
+```ts
+// the prop name will be inferred from variable name
+const propName = defineProp<T>()
+const propName = defineProp<T>(defaultValue)
+const propName = defineProp<T>(defaultValue, required)
+const propName = defineProp<T>(defaultValue, required, rest)
+```
+
+### Basic Usage
+
+```vue
+<script setup>
+// declare prop `count` with default value `0`
+const count = defineProp(0)
+
+// declare required prop `disabled`
+const disabled = defineProp(undefined, true)
+
+// access prop value
+console.log(count.value, disabled.value)
+</script>
+```
+
+### With Options
+
+```vue
+<script setup>
+// Declare prop with options
+const count = defineProp(0, false, {
+  type: Number,
+  validator: (value) => value < 20,
+})
+</script>
+```
+
+### TypeScript
+
+```vue
+<script setup lang="ts">
+const count = defineProp<number>()
+count.value
+//    ^? type: number | undefined
+
+// Declare prop of TS type boolean with default value
+const disabled = defineProp<boolean>(true)
+//    ^? type: boolean
+</script>
+```
+
+## Volar Configuration
+
+**Require Volar >= `1.3.12`**
+
+```jsonc
+// tsconfig.json
+{
+  // ...
+  "vueCompilerOptions": {
+    // "kevinEdition" | "johnsonEdition" | false
+    "experimentalDefinePropProposal": "kevinEdition"
+  }
+}
+```

docs/macros/index.md

@@ -20,6 +20,7 @@ Please make sure `unplugin-vue-macros` is set up correctly. If you haven't yet,
 
 ## Experimental Features
 
-- [singleDefine](/macros/single-define)
+- [defineProp](/macros/define-prop)
+- [defineEmit](/macros/define-emit)
 - [setupComponent](/macros/setup-component)
 - [setupSFC](/macros/setup-sfc)