docs: tweak "invalid assignment" compiler error message (#14955)

* docs: tweak "invalid assignment" compiler error message

fixes #14702

* tweak wording

---------

Co-authored-by: Rich Harris <[email protected]>

Author: dummdidumm

.changeset/sharp-dryers-try.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+chore: tweak "invalid assignment" compiler error message

documentation/docs/98-reference/.generated/compile-errors.md

@@ -331,7 +331,39 @@ The $ prefix is reserved, and cannot be used for variables and imports
 ### each_item_invalid_assignment
 
 ```
-Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`)
+Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`, or `bind:value={array[i]}` instead of `bind:value={entry}`)
+```
+
+In legacy mode, it was possible to reassign or bind to the each block argument itself:
+
+```svelte
+<script>
+	let array = [1, 2, 3];
+</script>
+
+{#each array as entry}
+	<!-- reassignment -->
+	<button on:click={() => entry = 4}>change</button>
+
+	<!-- binding -->
+	<input bind:value={entry}>
+{/each}
+```
+
+This turned out to be buggy and unpredictable, particularly when working with derived values (such as `array.map(...)`), and as such is forbidden in runes mode. You can achieve the same outcome by using the index instead:
+
+```svelte
+<script>
+	let array = $state([1, 2, 3]);
+</script>
+
+{#each array as entry, i}
+	<!-- reassignment -->
+	<button onclick={() => array[i] = 4}>change</button>
+
+	<!-- binding -->
+	<input bind:value={array[i]}>
+{/each}
 ```
 
 ### effect_invalid_placement

packages/svelte/messages/compile-errors/script.md

@@ -32,7 +32,39 @@
 
 ## each_item_invalid_assignment
 
-> Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`)
+> Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`, or `bind:value={array[i]}` instead of `bind:value={entry}`)
+
+In legacy mode, it was possible to reassign or bind to the each block argument itself:
+
+```svelte
+<script>
+	let array = [1, 2, 3];
+</script>
+
+{#each array as entry}
+	<!-- reassignment -->
+	<button on:click={() => entry = 4}>change</button>
+
+	<!-- binding -->
+	<input bind:value={entry}>
+{/each}
+```
+
+This turned out to be buggy and unpredictable, particularly when working with derived values (such as `array.map(...)`), and as such is forbidden in runes mode. You can achieve the same outcome by using the index instead:
+
+```svelte
+<script>
+	let array = $state([1, 2, 3]);
+</script>
+
+{#each array as entry, i}
+	<!-- reassignment -->
+	<button onclick={() => array[i] = 4}>change</button>
+
+	<!-- binding -->
+	<input bind:value={array[i]}>
+{/each}
+```
 
 ## effect_invalid_placement
 

packages/svelte/src/compiler/errors.js

@@ -151,12 +151,12 @@ export function dollar_prefix_invalid(node) {
 }
 
 /**
- * Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`)
+ * Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`, or `bind:value={array[i]}` instead of `bind:value={entry}`)
  * @param {null | number | NodeLike} node
  * @returns {never}
  */
 export function each_item_invalid_assignment(node) {
-	e(node, "each_item_invalid_assignment", `Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. \`array[i] = value\` instead of \`entry = value\`)\nhttps://svelte.dev/e/each_item_invalid_assignment`);
+	e(node, "each_item_invalid_assignment", `Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. \`array[i] = value\` instead of \`entry = value\`, or \`bind:value={array[i]}\` instead of \`bind:value={entry}\`)\nhttps://svelte.dev/e/each_item_invalid_assignment`);
 }
 
 /**

packages/svelte/tests/compiler-errors/samples/runes-invalid-each-binding-this/_config.js

@@ -4,6 +4,6 @@ export default test({
 	error: {
 		code: 'each_item_invalid_assignment',
 		message:
-			'Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`)'
+			'Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`, or `bind:value={array[i]}` instead of `bind:value={entry}`)'
 	}
 });

packages/svelte/tests/compiler-errors/samples/runes-invalid-each-binding/_config.js

@@ -4,6 +4,6 @@ export default test({
 	error: {
 		code: 'each_item_invalid_assignment',
 		message:
-			'Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`)'
+			'Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`, or `bind:value={array[i]}` instead of `bind:value={entry}`)'
 	}
 });

packages/svelte/tests/compiler-errors/samples/runes-invalid-each-mutation/_config.js

@@ -4,6 +4,6 @@ export default test({
 	error: {
 		code: 'each_item_invalid_assignment',
 		message:
-			'Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`)'
+			'Cannot reassign or bind to each block argument in runes mode. Use the array and index variables instead (e.g. `array[i] = value` instead of `entry = value`, or `bind:value={array[i]}` instead of `bind:value={entry}`)'
 	}
 });