From d2370797780434b4fd9897d0e01df7a38ad8734a Mon Sep 17 00:00:00 2001
From: Bobbie Goede <bobbiegoede@gmail.com>
Date: Thu, 30 May 2024 01:44:00 +0200
Subject: [PATCH] docs: add documentation for `<Motion>` component (#192)

* docs: add documentation for `<Motion>` component

* docs: disable `devLogs` to prevent infinite error loop

* docs: add basic examples to components page
---
 .../content/examples/MotionComponent.vue      | 40 ++++++++
 .../content/examples/MotionGroupComponent.vue | 58 ++++++++++++
 docs/content/2.features/7.components.md       | 91 +++++++++++++++++++
 docs/nuxt.config.ts                           |  3 +
 4 files changed, 192 insertions(+)
 create mode 100644 docs/components/content/examples/MotionComponent.vue
 create mode 100644 docs/components/content/examples/MotionGroupComponent.vue
 create mode 100644 docs/content/2.features/7.components.md

diff --git a/docs/components/content/examples/MotionComponent.vue b/docs/components/content/examples/MotionComponent.vue
new file mode 100644
index 00000000..4f3539b4
--- /dev/null
+++ b/docs/components/content/examples/MotionComponent.vue
@@ -0,0 +1,40 @@
+<script lang="ts" setup></script>
+
+<template>
+  <div class="example-wrapper">
+    <div class="example-hint">Scroll down to trigger motion!</div>
+    <Motion is="p" preset="slideVisibleLeft">
+      <div class="example-target">Text in Motion!</div>
+    </Motion>
+  </div>
+</template>
+
+<style scoped>
+.example-wrapper {
+  height: 200px;
+  width: 100%;
+  overflow-y: scroll;
+  overflow-x: hidden;
+  text-align: center;
+  border: 1px solid #222;
+  border-radius: 0.5em;
+}
+
+.example-hint,
+p {
+  display: flex;
+  flex: 1 0;
+
+  align-items: center;
+  justify-content: center;
+
+  height: 100%;
+  padding: 2em;
+}
+
+.example-target {
+  padding: 1em;
+  background-color: #111;
+  border-radius: 0.5em;
+}
+</style>
diff --git a/docs/components/content/examples/MotionGroupComponent.vue b/docs/components/content/examples/MotionGroupComponent.vue
new file mode 100644
index 00000000..7770df4d
--- /dev/null
+++ b/docs/components/content/examples/MotionGroupComponent.vue
@@ -0,0 +1,58 @@
+<script lang="ts" setup></script>
+
+<template>
+  <div class="example-wrapper">
+    <div class="example-hint">Scroll down to trigger motion!</div>
+    <MotionGroup preset="slideVisibleLeft" :duration="600">
+      <section>
+        <h3>Product 1</h3>
+        <p>Description text</p>
+      </section>
+      <section>
+        <h3>Product 2</h3>
+        <p>Description text</p>
+      </section>
+      <section>
+        <h3>Product 3</h3>
+        <p>Description text</p>
+      </section>
+    </MotionGroup>
+  </div>
+</template>
+
+<style scoped>
+.example-wrapper {
+  height: 200px;
+  width: 100%;
+  overflow-y: scroll;
+  overflow-x: hidden;
+  text-align: center;
+  border: 1px solid #222;
+  border-radius: 0.5em;
+}
+
+.example-hint,
+p,
+section {
+  display: flex;
+  flex-direction: column;
+
+  flex: 1 0;
+  align-items: center;
+  justify-content: center;
+
+  height: 100%;
+  padding: 2em;
+}
+
+section {
+  background-color: #111;
+  height: calc(100% / 3);
+}
+
+section h3,
+section p {
+  margin: 0.5em !important;
+  padding: 0 !important;
+}
+</style>
diff --git a/docs/content/2.features/7.components.md b/docs/content/2.features/7.components.md
new file mode 100644
index 00000000..e174ec17
--- /dev/null
+++ b/docs/content/2.features/7.components.md
@@ -0,0 +1,91 @@
+# Components
+
+vueuse/motion allows you to implement your animations directly within the template of your components without the need to wrap target elements in any additional components.
+
+These components work similar to the directive `v-motion` usage but work better in projects using server-side rendering.
+
+## `<Motion>`
+
+Example of a `<Motion>` component using a motion preset on a `<p>` element:
+
+```vue
+<template>
+  <Motion is="p" preset="slideVisibleLeft">Text in Motion!</Motion>
+</template>
+```
+
+<MotionComponent></MotionComponent>
+
+## `<MotionGroup>`
+
+The `<MotionGroup>` can be used to apply motion configuration to all of its child elements, this component is renderless by default and can be used as a wrapper by passing a value to the `:is` prop.
+
+```vue
+<template>
+  <MotionGroup preset="slideVisibleLeft" :duration="600">
+    <section>
+      <h3>Product 1</h3>
+      <p>Description text</p>
+    </section>
+    <section>
+      <h3>Product 2</h3>
+      <p>Description text</p>
+    </section>
+    <section>
+      <h3>Product 3</h3>
+      <p>Description text</p>
+    </section>
+  </MotionGroup>
+</template>
+```
+
+<MotionGroupComponent></MotionGroupComponent>
+
+
+## Props
+
+The `<Motion>` and `<MotionGroup>` components allow you to define animation properties (variants) as props.
+
+- **`is`**: What element should rendered (`div` by default for `<Motion>`).
+- **`preset`**: Motion preset to use (expects camel-case string), see [Presets](/features/presets).
+
+### Variant props
+
+- **`initial`**: Properties the element will have before it is mounted.
+- **`enter`**: Properties the element will have after it is mounted.
+- **`visible`**: Properties the element will have whenever it is within view. Once out of view, the `initial` properties are reapplied.
+- **`visible-once`**: Properties the element will have once it enters the view.
+- **`hovered`**: Properties the element will have when hovered.
+- **`focused`**: Properties the element will have when it receives focus.
+- **`tapped`**: Properties the element will have upon being clicked or tapped.
+
+Variants can be passed as an object using the `:variants` prop.
+
+The `:variants` prop combines with other variant properties, allowing for the definition of custom variants from this object.
+
+Additional variant properties can be explored on the [Variants](/features/variants) page.
+
+### Shorthand Props
+
+We support shorthand props for quickly setting transition properties:
+
+- **`delay`**
+- **`duration`**
+
+These properties apply to `visible`, `visible-once`, or `enter` variants if specified; otherwise, they default to the `initial` variant.
+
+```vue
+<template>
+  <Motion
+    :initial="{ opacity: 0, y: 100 }"
+    :enter="{ opacity: 1, y: 0, scale: 1 }"
+    :variants="{ custom: { scale: 2 } }"
+    :hovered="{ scale: 1.2 }"
+    :delay="200"
+    :duration="1200"
+  >
+    Content to animate!
+  </Motion>
+</template>
+```
+
diff --git a/docs/nuxt.config.ts b/docs/nuxt.config.ts
index 420f12fe..6acd32d0 100644
--- a/docs/nuxt.config.ts
+++ b/docs/nuxt.config.ts
@@ -7,6 +7,9 @@ export default defineNuxtConfig({
     '@vueuse/motion/nuxt': resolve(__dirname, '../src/nuxt/module.ts'),
   },
   modules: ['@vueuse/motion/nuxt'],
+  features: {
+    devLogs: false,
+  },
   typescript: {
     includeWorkspace: true,
   },