From f203dea1eccc8bf8670152af2cf5bffef523547b Mon Sep 17 00:00:00 2001
From: braks <78412429+bcakmakoglu@users.noreply.github.com>
Date: Mon, 13 Nov 2023 21:47:30 +0100
Subject: [PATCH] docs(guide): add controlled flow guide page

---
 docs/src/.vitepress/config.mts    |   1 +
 docs/src/guide/composables.md     |   4 +
 docs/src/guide/controlled-flow.md | 123 ++++++++++++++++++++++++++++++
 docs/src/guide/edge.md            |   4 +
 docs/src/guide/getting-started.md |   6 +-
 docs/src/guide/index.md           |   2 +-
 docs/src/guide/node.md            |   4 +
 docs/src/guide/theming.md         |   4 +
 8 files changed, 146 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/guide/controlled-flow.md

diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts
index 333f2ab0..7d64b0e4 100644
--- a/docs/src/.vitepress/config.mts
+++ b/docs/src/.vitepress/config.mts
@@ -157,6 +157,7 @@ export default defineConfigWithTheme<DefaultTheme.Config>({
             { text: 'Nodes', link: '/guide/node' },
             { text: 'Edges', link: '/guide/edge' },
             { text: 'Composables', link: '/guide/composables' },
+            { text: 'Controlled Flow', link: '/guide/controlled-flow' },
           ],
         },
         {
diff --git a/docs/src/guide/composables.md b/docs/src/guide/composables.md
index 5bdb2dac..8df41fd9 100644
--- a/docs/src/guide/composables.md
+++ b/docs/src/guide/composables.md
@@ -1,3 +1,7 @@
+---
+title: Composables
+---
+
 # Composables
 
 ## [useVueFlow](/typedocs/functions/useVueFlow)
diff --git a/docs/src/guide/controlled-flow.md b/docs/src/guide/controlled-flow.md
new file mode 100644
index 00000000..d5662424
--- /dev/null
+++ b/docs/src/guide/controlled-flow.md
@@ -0,0 +1,123 @@
+---
+title: Controlled Flow
+---
+
+# Taking Control of Vue Flow
+
+Vue Flow is designed to be flexible and customizable, allowing you to take control of the flow of your application.
+By default, Vue Flow will apply changes automatically, so you don't have to worry about it.
+
+::: warning
+This API is subject to change in the next major release where changes will *most likely* not be applied automatically anymore.
+:::
+
+Though, there are cases where you want to take control of changes and apply them manually after some processing and validations for example.
+
+This guide will show you how to take control of Vue Flow and apply these changes manually.
+
+## The `applyChanges` option
+
+The `applyChanges` option is a flag that can be passed to the `VueFlow` component to enable or disable automatic change handling.
+
+By setting this option to `false`, we tell Vue Flow to not apply changes automatically anymore.
+
+```vue
+<template>
+  <VueFlow v-model="elements" :apply-changes="false" />
+</template>
+```
+
+## `onNodesChange` / `onEdgesChange` events
+
+Vue Flow provides two events that can be used to listen to changes on nodes and edges.
+These events are emitted regardless of the `applyChanges` option, so you can use them to listen to changes even if you have automatic changes enabled.
+
+```vue
+<script setup>
+const onChange = (changes) => {
+  // changes are arrays of type `NodeChange` or `EdgeChange`
+  console.log(changes) // will log the changes
+}
+</script>
+
+<template>
+  <VueFlow v-model="elements" @nodes-change="onChange" @edges-change="onChange" />
+</template>
+```
+
+## `applyNodeChanges` / `applyEdgeChanges`
+
+Vue Flow provides two functions that can be used to apply changes manually.
+
+These functions are available from the `useVueFlow` composable.
+
+```vue
+<script setup>
+import { useVueFlow } from '@vue-flow/core'
+
+const { applyNodeChanges, applyEdgeChanges } = useVueFlow();
+
+const onChange = (changes) => {
+  // apply changes manually
+  applyNodeChanges(changes)
+}
+</script>
+```
+
+## Validating Changes
+
+Using what we just learned, we can now take control of changes and apply them manually.
+
+In this example, we will first disable automatic change handlers with `applyChanges`, 
+then use the `onNodesChange` event to listen to changes and validate delete changes and, 
+if they are valid, use `applyNodeChanges` to apply them.
+
+```vue
+<script setup>
+import { useVueFlow, VueFlow } from '@vue-flow/core'
+import { ref } from 'vue'
+
+const { applyNodeChanges } = useVueFlow();
+
+const { confirm } = useConfirm();
+
+const elements = ref([
+  {
+    id: '1',
+    label: 'Node 1',
+    position: { x: 0, y: 0 },
+  },
+  {
+    id: '2',
+    label: 'Node 2',
+    position: { x: 100, y: 100 },
+  },
+  {
+    id: 'e1-2',
+    source: '1',
+    target: '2',
+  },
+])
+
+const onNodesChange = (changes) => {
+    changes.forEach(async (change) => {
+        // if the change is a remove change, we want to validate it first
+        if (change.type === 'remove') {
+          const isConfirmed = await confirm();
+
+          if (isConfirmed) {
+            // if confirmed, apply the change
+            applyNodeChanges([change])
+          }
+        } else {
+          // apply all other changes
+          applyNodeChanges([change])
+        }
+    })
+}
+</script>
+
+<template>
+  <VueFlow v-model="elements" :apply-changes="false" @nodes-change="onNodesChange" />
+</template>
+```
diff --git a/docs/src/guide/edge.md b/docs/src/guide/edge.md
index ef13110b..a40d81c2 100644
--- a/docs/src/guide/edge.md
+++ b/docs/src/guide/edge.md
@@ -1,3 +1,7 @@
+---
+title: Edges
+---
+
 <script setup>
 import LogosJavascript from '~icons/logos/javascript';
 import LogosTypescript from '~icons/logos/typescript-icon';
diff --git a/docs/src/guide/getting-started.md b/docs/src/guide/getting-started.md
index c98b35c8..16f6aac7 100644
--- a/docs/src/guide/getting-started.md
+++ b/docs/src/guide/getting-started.md
@@ -1,3 +1,7 @@
+---
+title: Getting Started
+---
+
 <script setup>
 import LogosJavascript from '~icons/logos/javascript';
 import LogosTypescript from '~icons/logos/typescript-icon';
@@ -17,7 +21,7 @@ Before you strap in, make sure you're equipped with:
 
 # CodeSandbox
 
-If you're looking for a quick way to get started, check out our [CodeSandbox template](https://codesandbox.io/p/sandbox/vue-flow-basic-gfgro4).
+If you're looking for a quick way to get started, check out the [CodeSandbox template](https://codesandbox.io/p/sandbox/vue-flow-basic-gfgro4).
 
 ## Installation
 
diff --git a/docs/src/guide/index.md b/docs/src/guide/index.md
index e0e6c996..a80bb240 100644
--- a/docs/src/guide/index.md
+++ b/docs/src/guide/index.md
@@ -30,7 +30,7 @@ bespoke nodes and edges.
 Additional components such as Background, Minimap, and Controls further enrich the interface,
 transforming your creations into engaging platforms.
 
-Explore the [examples](/examples/) if you're eager to jump right in and get your hands on some code!
+Explore the [examples](/examples/) or checkout the [CodeSandbox template](https://codesandbox.io/p/sandbox/vue-flow-basic-gfgro4) if you're eager to jump right in and get your hands on some code!
 
 ## <span class="flex gap-2 items-center"><Flash class="text-yellow-500" /> Key Features</span>
 
diff --git a/docs/src/guide/node.md b/docs/src/guide/node.md
index e6ccbeb2..ff9500b2 100644
--- a/docs/src/guide/node.md
+++ b/docs/src/guide/node.md
@@ -1,3 +1,7 @@
+---
+title: Nodes
+---
+
 <script setup>
 import LogosJavascript from '~icons/logos/javascript';
 import LogosTypescript from '~icons/logos/typescript-icon';
diff --git a/docs/src/guide/theming.md b/docs/src/guide/theming.md
index 6670f4cc..2ba170a6 100644
--- a/docs/src/guide/theming.md
+++ b/docs/src/guide/theming.md
@@ -1,3 +1,7 @@
+---
+title: Theming
+---
+
 <script setup>
 import LogosJavascript from '~icons/logos/javascript';
 import { ref, h } from 'vue';