docs: add section on changes

docs/src/guide/controlled-flow.md

@@ -4,16 +4,83 @@ 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.
+This API is subject to change in the next major release where changes will not be applied automatically anymore.
 :::
 
+By default, Vue Flow will apply *changes* automatically, so you don't have to worry about it.
+
 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.
+In this guide, we will learn how to take control of changes and apply them manually.
+
+## What is a [Change](https://vueflow.dev/typedocs/types/NodeChange.html)?
+
+A *change* is anything that is triggered by an interaction with the flow, like adding, updating (position, selected), or removing a node or an edge, either
+by dragging, clicking etc. or by using the provided API.
+
+These changes are communicated to the user-land through the `onNodesChange` and `onEdgesChange` events.
+
+Possible Changes include:
+
+- [`add`](https://vueflow.dev/typedocs/interfaces/NodeAddChange.html): A node or an edge was added.
+- [`remove`](https://vueflow.dev/typedocs/interfaces/NodeRemoveChange.html): A node or an edge was removed.
+- [`select`](https://vueflow.dev/typedocs/interfaces/NodeSelectionChange.html): A node or an edge was selected/unselected.
+- [`position`](https://vueflow.dev/typedocs/interfaces/NodePositionChange.html): A nodes' position was updated.
+- [`dimensions`](https://vueflow.dev/typedocs/interfaces/NodeDimensionChange.html): A nodes' dimensions were updated.
+
+::: warning
+Changes *do not* refer to *any* change in the flow, like zooming or panning, or just updating the `data` object of a node.
+:::
+
+### Why is no change emitted when I update a node?
+
+Vue Flow will not track your nodes/edges and try to figure out what changed, it will only emit changes when you interact with the flow or use the API.
+
+For example this *will not* emit a change:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const nodes = ref([
+  {
+    id: '1',
+    position: { x: 0, y: 0 },
+    data: { label: 'Node 1' },
+  },
+])
+
+// this function *will not* emit a change
+function removeNode() {
+  nodes.value = nodes.value.filter((node) => node.id !== '1')
+}
+</script>
+```
+
+This is because Vue Flow does not know that the node with id `1` was removed, it only knows about changes that are triggered by the user or the API.
+
+This, for example, *will* emit a change:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { useVueFlow } from '@vue-flow/core'
+
+const nodes = ref([
+  {
+    id: '1',
+    position: { x: 0, y: 0 },
+    data: { label: 'Node 1' },
+  },
+])
+
+// this function *will* emit a change
+const { removeNodes } = useVueFlow()
+
+removeNodes('1')
+</script>
+```
 
 ## The `applyChanges` option
 
@@ -88,7 +155,7 @@ then use the `onNodesChange` event to listen to changes and validate delete chan
 if they are valid, use `applyNodeChanges` to apply them.
 
 ::: info
-Checkout the [confirm delete example](/examples/confirm).
+Checkout the [confirm delete example](/examples/confirm.html).
 :::
 
 ```vue

docs/src/guide/edge.md

@@ -92,6 +92,10 @@ For the full list of options available for an edge, check out the [Edge Type](/t
 
 Edges are rendered by passing them to the `edges` prop (or the deprecated `v-model` prop) of the Vue Flow component.
 
+:::warning
+This method will *not* create a change. Check out the [Controlled Flow](/guide/controlled-flow.html) section for more information.
+:::
+
 :::code-group
 
 ```vue [<LogosJavascript />]

docs/src/guide/node.md

@@ -64,6 +64,10 @@ For the full list of options available for a node, check out the [Node Interface
 
 Nodes are rendered by passing them to the `nodes` prop (or the deprecated `v-model` prop) of the Vue Flow component.
 
+:::warning
+This method will *not* create a change. Check out the [Controlled Flow](/guide/controlled-flow.html) section for more information.
+:::
+
 :::code-group
 
 ```vue [<LogosJavascript />]