Merge pull request #81 from DennisSmuda/docs/use-motion-value

docs: add "useMotionValueEvent" content + fix errors

docs/components/layout/IsLand.vue

@@ -19,7 +19,7 @@ const open = ref(false)
 const scrollPercentage = ref(0)
 const { scrollYProgress } = useScroll()
 
-useMotionValue(scrollYProgress, 'change', (value) => {
+useMotionValueEvent(scrollYProgress, 'change', (value) => {
   scrollPercentage.value = value
 })
 

docs/content/4.motion-value/0.overview.md

@@ -53,7 +53,7 @@ const opacity = useTransform(
 
 ## Usage
 
-Motion values can be created with the [`useMotionValue`](/motion-value/use-motion-value-event) composable. The string or number passed to `useMotionValue` will act as its initial state.
+Motion values can be created with the `useMotionValue` composable. The string or number passed to `useMotionValue` will act as its initial state.
 
 ```ts
 import { useMotionValue } from 'motion-v'
@@ -99,10 +99,10 @@ For strings and colors, `getVelocity` will always return 0.
 
 ### Events
 
-Listeners can be added to motion values via the `on` method or the [`useMotionValue`](/motion-value/use-motion-value-event) composable.
+Listeners can be added to motion values via the `on` method or the [`useMotionValueEvent`](/motion-value/use-motion-value-event) composable.
 
 ```ts
-useMotionValue(x, 'change', latest => console.log(latest))
+useMotionValueEvent(x, 'change', latest => console.log(latest))
 ```
 Available events are `"change"`, `"animationStart"`, `"animationComplete"` `"animationCancel"`.
 
@@ -182,7 +182,7 @@ It returns a function that, when called, will unsubscribe the listener.
 const unsubscribe = x.on('change', latest => console.log(latest))
 ```
 
-You can `on` inside a vue component, or instead use the [`useMotionValue`](/motion-value/use-motion-value-event) composable.
+You can use `on` inside a vue component, or instead use the [`useMotionValueEvent`](/motion-value/use-motion-value-event) composable.
 
 ### `destroy()`
 

docs/content/4.motion-value/1.use-motion-value-event.md

@@ -4,4 +4,68 @@ description:
 navigation.icon: 'lucide:ear'
 ---
 
+`useMotionValueEvent` manages a motion value event handler throughout the lifecycle of a vue component.
+
+```vue
+<script setup lang="ts">
+import { useMotionValue } from 'motion-v'
+
+const x = useMotionValue(0)
+
+useMotionValueEvent(x, 'animationStart', () => {
+  console.log('animation has started')
+})
+</script>
+
+<template>
+  <Motion
+    style:="{ x }"
+  />
+</template>
+```
+
+When the component is unmounted, event handlers will be safely cleaned up.
+
+## Usage
+
+Import from Motion Vue:
+
+```ts
+import { useMotionValueEvent } from 'motion-v'
+```
+
+To add an event listener to a motion value, provide the value, event name and callback:
+
+```ts
+const color = useMotionValue('#00f')
+
+useMotionValueEvent(color, 'change', (latest) => {
+  console.log(latest)
+})
+```
+
+Available events are:
+
+- `change`
+- `animationStart`
+- `animationComplete`
+- `animationCancel`
+
+`change` events are provided the latest value of the motion value.
+
+## Advanced
+
+`useMotionValueEvent` is a helper function for a motion value's [on method](/motion-value/overview#on). With `on`, you can start listening to events whenever you like, for instance within an event handler. But remember to also unsubscribe when the component unmounts.
+
 - [Motion React-useMotionValueEvent](https://motion.dev/docs/react-use-motion-value-event)
+
+```ts
+function doSomething() {}
+
+const color = useMotionValue('#00f')
+const unsub = color.on('change', doSomething)
+
+onUnmounted(() => {
+  unsub()
+})
+```