docs: added events as props and typing with object based emits (#2583)

* docs: added events as props and typing with object based emits

* Apply suggestions from code review

Co-authored-by: Natalia Tepluhina <[email protected]>

* remove info

---------

Co-authored-by: Natalia Tepluhina <[email protected]>

Author: pikax

src/guide/components/events.md

@@ -17,6 +17,7 @@ if (typeof window !== 'undefined') {
   }
 }
 </script>
+
 # Component Events {#component-events}
 
 > This page assumes you've already read the [Components Basics](/guide/essentials/component-basics). Read that first if you are new to components.
@@ -176,14 +177,14 @@ export default {
 
 </div>
 
-The `emits` option and `defineEmits()` macro also support an object syntax, which allows us to perform runtime validation of the payload of the emitted events:
+The `emits` option and `defineEmits()` macro also support an object syntax. If using TypeScript you can type arguments, which allows us to perform runtime validation of the payload of the emitted events:
 
 <div class="composition-api">
 
 ```vue
 <script setup>
 const emit = defineEmits({
-  submit(payload) {
+  submit(payload: { email: string, password: string }) {
     // return `true` or `false` to indicate
     // validation pass / fail
   }
@@ -210,7 +211,7 @@ More details: [Typing Component Emits](/guide/typescript/composition-api#typing-
 ```js
 export default {
   emits: {
-    submit(payload) {
+    submit(payload: { email: string, password: string }) {
       // return `true` or `false` to indicate
       // validation pass / fail
     }
@@ -287,3 +288,14 @@ export default {
 ```
 
 </div>
+
+## Events as Props {#events-props}
+
+You may also declare and pass `events` as `props`, by prefixing the capitalized event name with `on`
+Using `props.onEvent` has a different behaviour than using `emit('event')`, as the former will pass only handle the property based listener (either `@event` or `:on-event`)
+
+:::warning
+If both `:onEvent` and `@event` are passed `props.onEvent` might be an array of `functions` instead of `function`, this behavior is not stable and might change in the future.
+:::
+
+Because of this, it is recommended to use `emit('event')` instead of `props.onEvent` when emitting events.

src/guide/typescript/composition-api.md

@@ -143,6 +143,18 @@ In `<script setup>`, the `emit` function can also be typed using either runtime
 // runtime
 const emit = defineEmits(['change', 'update'])
 
+// options based
+const emit = defineEmits({
+  change: (id: number) => {
+    // return `true` or `false` to indicate
+    // validation pass / fail
+  },
+  update: (value: string) => {
+    // return `true` or `false` to indicate
+    // validation pass / fail
+  }
+})
+
 // type-based
 const emit = defineEmits<{
   (e: 'change', id: number): void