document callback

Author: Rich-Harris

documentation/docs/03-runes/01-state.md

@@ -89,6 +89,24 @@ console.log(a, b); // 3, 3
 
 As with `$state`, if `$state.link` is passed a plain object or array it will be made deeply reactive. If passed an existing state proxy it will be reused, meaning that mutating the linked state will mutate the original. To clone a state proxy, you can use [`$state.snapshot`](#$state-snapshot).
 
+If you pass a callback to `$state.link`, changes to the input value will invoke the callback rather than updating the linked state, allowing you to choose whether to (for example) preserve or discard local changes, or merge incoming changes with local ones:
+
+```js
+let { stuff } = $props();
+
+let incoming = $state();
+let hasUnsavedChanges = $state(false);
+
+let current = $state.link({ ...stuff }, (stuff) => {
+	if (hasUnsavedChanges) {
+		incoming = stuff;
+	} else {
+		incoming = null;
+		current = stuff;
+	}
+});
+```
+
 ## `$state.raw`
 
 State declared with `$state.raw` cannot be mutated; it can only be _reassigned_. In other words, rather than assigning to a property of an object, or using an array method like `push`, replace the object or array altogether if you'd like to update it:

sites/svelte-5-preview/src/routes/docs/content/01-api/02-runes.md

@@ -91,6 +91,24 @@ console.log(a, b); // 3, 3
 
 As with `$state`, if `$state.link` is passed a plain object or array it will be made deeply reactive. If passed an existing state proxy it will be reused, meaning that mutating the linked state will mutate the original. To clone a state proxy, you can use [`$state.snapshot`](#$state-snapshot).
 
+If you pass a callback to `$state.link`, changes to the input value will invoke the callback rather than updating the linked state, allowing you to choose whether to (for example) preserve or discard local changes, or merge incoming changes with local ones:
+
+```js
+let { stuff } = $props();
+
+let incoming = $state();
+let hasUnsavedChanges = $state(false);
+
+let current = $state.link({ ...stuff }, (stuff) => {
+	if (hasUnsavedChanges) {
+		incoming = stuff;
+	} else {
+		incoming = null;
+		current = stuff;
+	}
+});
+```
+
 ## `$state.raw`
 
 State declared with `$state.raw` cannot be mutated; it can only be _reassigned_. In other words, rather than assigning to a property of an object, or using an array method like `push`, replace the object or array altogether if you'd like to update it: