docs(guide): add controlled flow guide page

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' },
           ],
         },
         {

docs/src/guide/composables.md

@@ -1,3 +1,7 @@
+---
+title: Composables
+---
+
 # Composables
 
 ## [useVueFlow](/typedocs/functions/useVueFlow)

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>
+```

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';

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
 

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>
 

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';

docs/src/guide/theming.md

@@ -1,3 +1,7 @@
+---
+title: Theming
+---
+
 <script setup>
 import LogosJavascript from '~icons/logos/javascript';
 import { ref, h } from 'vue';