merge main

Author: Rich-Harris

.changeset/big-hats-wonder.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+fix: always run `if` block code the first time

.changeset/rare-cheetahs-laugh.md

@@ -36,12 +36,7 @@ let todos = $state([
 ...modifying an individual todo's property will trigger updates to anything in your UI that depends on that specific property:
 
 ```js
-// @filename: ambient.d.ts
-declare global {
-	const todos: Array<{ done: boolean, text: string }>
-}
-
-// @filename: index.js
+let todos = [{ done: false, text: 'add more todos' }];
 // ---cut---
 todos[0].done = !todos[0].done;
 ```
@@ -64,6 +59,17 @@ todos.push({
 
 > [!NOTE] When you update properties of proxies, the original object is _not_ mutated.
 
+Note that if you destructure a reactive value, the references are not reactive — as in normal JavaScript, they are evaluated at the point of destructuring:
+
+```js
+let todos = [{ done: false, text: 'add more todos' }];
+// ---cut---
+let { done, text } = todos[0];
+
+// this will not affect the value of `done`
+todos[0].done = !todos[0].done;
+```
+
 ### Classes
 
 You can also use `$state` in class fields (whether public or private):
@@ -85,7 +91,42 @@ class Todo {
 }
 ```
 
-> [!NOTE] The compiler transforms `done` and `text` into `get`/`set` methods on the class prototype referencing private fields.
+> [!NOTE] The compiler transforms `done` and `text` into `get`/`set` methods on the class prototype referencing private fields. This means the properties are not enumerable.
+
+When calling methods in JavaScript, the value of [`this`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this) matters. This won't work, because `this` inside the `reset` method will be the `<button>` rather than the `Todo`:
+
+```svelte
+<button onclick={todo.reset}>
+	reset
+</button>
+```
+
+You can either use an inline function...
+
+```svelte
+<button onclick=+++{() => todo.reset()}>+++
+	reset
+</button>
+```
+
+...or use an arrow function in the class definition:
+
+```js
+// @errors: 7006 2554
+class Todo {
+	done = $state(false);
+	text = $state();
+
+	constructor(text) {
+		this.text = text;
+	}
+
+	+++reset = () => {+++
+		this.text = '';
+		this.done = false;
+	}
+}
+```
 
 ## `$state.raw`
 
@@ -127,3 +168,90 @@ To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snaps
 ```
 
 This is handy when you want to pass some state to an external library or API that doesn't expect a proxy, such as `structuredClone`.
+
+## Passing state into functions
+
+JavaScript is a _pass-by-value_ language — when you call a function, the arguments are the _values_ rather than the _variables_. In other words:
+
+```js
+/// file: index.js
+// @filename: index.js
+// ---cut---
+/**
+ * @param {number} a
+ * @param {number} b
+ */
+function add(a, b) {
+	return a + b;
+}
+
+let a = 1;
+let b = 2;
+let total = add(a, b);
+console.log(total); // 3
+
+a = 3;
+b = 4;
+console.log(total); // still 3!
+```
+
+If `add` wanted to have access to the _current_ values of `a` and `b`, and to return the current `total` value, you would need to use functions instead:
+
+```js
+/// file: index.js
+// @filename: index.js
+// ---cut---
+/**
+ * @param {() => number} getA
+ * @param {() => number} getB
+ */
+function add(+++getA, getB+++) {
+	return +++() => getA() + getB()+++;
+}
+
+let a = 1;
+let b = 2;
+let total = add+++(() => a, () => b)+++;
+console.log(+++total()+++); // 3
+
+a = 3;
+b = 4;
+console.log(+++total()+++); // 7
+```
+
+State in Svelte is no different — when you reference something declared with the `$state` rune...
+
+```js
+let a = +++$state(1)+++;
+let b = +++$state(2)+++;
+```
+
+...you're accessing its _current value_.
+
+Note that 'functions' is broad — it encompasses properties of proxies and [`get`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get)/[`set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) properties...
+
+```js
+/// file: index.js
+// @filename: index.js
+// ---cut---
+/**
+ * @param {{ a: number, b: number }} input
+ */
+function add(input) {
+	return {
+		get value() {
+			return input.a + input.b;
+		}
+	};
+}
+
+let input = $state({ a: 1, b: 2 });
+let total = add(input);
+console.log(total.value); // 3
+
+input.a = 3;
+input.b = 4;
+console.log(total.value); // 7
+```
+
+...though if you find yourself writing code like that, consider using [classes](#Classes) instead.

documentation/docs/02-runes/02-$state.md

@@ -74,6 +74,30 @@ You can freely use destructuring and rest patterns in each blocks.
 {/each}
 ```
 
+## Each blocks without an item
+
+```svelte
+<!--- copy: false  --->
+{#each expression}...{/each}
+```
+
+```svelte
+<!--- copy: false  --->
+{#each expression, index}...{/each}
+```
+
+In case you just want to render something `n` times, you can omit the `as` part ([demo](/playground/untitled#H4sIAAAAAAAAE3WR0W7CMAxFf8XKNAk0WsSeUEaRpn3Guoc0MbQiJFHiMlDVf18SOrZJ48259_jaVgZmxBEZZ28thgCNFV6xBdt1GgPj7wOji0t2EqI-wa_OleGEmpLWiID_6dIaQkMxhm1UdwKpRQhVzWSaVORJNdvWpqbhAYVsYQCNZk8thzWMC_DCHMZk3wPSThNQ088I3mghD9UwSwHwlLE5PMIzVFUFq3G7WUZ2OyUvU3JOuZU332wCXTRmtPy1NgzXZtUFp8WFw9536uWqpbIgPEaDsJBW90cTOHh0KGi2XsBq5-cT6-3nPauxXqHnsHJnCFZ3CvJVkyuCQ0mFF9TZyCQ162WGvteLKfG197Y3iv_pz_fmS68Hxt8iPBPj5HscP8YvCNX7uhYCAAA=)):
+
+```svelte
+<div class="chess-board">
+	{#each { length: 8 }, rank}
+		{#each { length: 8 }, file}
+			<div class:black={(rank + file) % 2 === 1}></div>
+		{/each}
+	{/each}
+</div>
+```
+
 ## Else blocks
 
 ```svelte

documentation/docs/03-template-syntax/03-each.md

@@ -246,6 +246,23 @@ We can tighten things up further by declaring a generic, so that `data` and `row
 </script>
 ```
 
+## Exporting snippets
+
+Snippets declared at the top level of a `.svelte` file can be exported from a `<script module>` for use in other components, provided they don't reference any declarations in a non-module `<script>` (whether directly or indirectly, via other snippets) ([demo](/playground/untitled#H4sIAAAAAAAAE3WPwY7CMAxEf8UyB1hRgdhjl13Bga8gHFJipEqtGyUGFUX5dxJUtEB3b9bYM_MckHVLWOKut50TMuC5tpbEY4GnuiGP5T6gXG0-ykLSB8vW2oW_UCNZq7Snv_Rjx0Kc4kpc-6OrrfwoVlK3uQ4CaGMgwsl1LUwXy0f54J9-KV4vf20cNo7YkMu22aqAz4-oOLUI9YKluDPF4h_at-hX5PFyzA1tZ84N3fGpf8YfUU6GvDumLqDKmEqCjjCHUEX4hqDTWCU5PJ6Or38c4g1cPu9tnAEAAA==)):
+
+```svelte
+<script module>
+	export { add };
+</script>
+
+{#snippet add(a, b)}
+	{a} + {b} = {a + b}
+{/snippet}
+```
+
+> [!NOTE]
+> This requires Svelte 5.5.0 or newer
+
 ## Programmatic snippets
 
 Snippets can be created programmatically with the [`createRawSnippet`](svelte#createRawSnippet) API. This is intended for advanced use cases.

documentation/docs/03-template-syntax/06-snippet.md

@@ -53,6 +53,22 @@ In the case of a numeric input (`type="number"` or `type="range"`), the value wi
 
 If the input is empty or invalid (in the case of `type="number"`), the value is `undefined`.
 
+Since 5.6.0, if an `<input>` has a `defaultValue` and is part of a form, it will revert to that value instead of the empty string when the form is reset. Note that for the initial render the value of the binding takes precedence unless it is `null` or `undefined`.
+
+```svelte
+<script>
+	let value = $state('');
+</script>
+
+<form>
+	<input bind:value defaultValue="not the empty string">
+	<input type="reset" value="Reset">
+</form>
+```
+
+> [!NOTE]
+> Use reset buttons sparingly, and ensure that users won't accidentally click them while trying to submit the form.
+
 ## `<input bind:checked>`
 
 Checkbox and radio inputs can be bound with `bind:checked`:
@@ -64,16 +80,29 @@ Checkbox and radio inputs can be bound with `bind:checked`:
 </label>
 ```
 
+Since 5.6.0, if an `<input>` has a `defaultChecked` attribute and is part of a form, it will revert to that value instead of `false` when the form is reset. Note that for the initial render the value of the binding takes precedence unless it is `null` or `undefined`.
+
+```svelte
+<script>
+	let checked = $state(true);
+</script>
+
+<form>
+	<input type="checkbox" bind:checked defaultChecked={true}>
+	<input type="reset" value="Reset">
+</form>
+```
+
 ## `<input bind:group>`
 
 Inputs that work together can use `bind:group`.
 
 ```svelte
 <script>
-	let tortilla = 'Plain';
+	let tortilla = $state('Plain');
 
 	/** @type {Array<string>} */
-	let fillings = [];
+	let fillings = $state([]);
 </script>
 
 <!-- grouped radio inputs are mutually exclusive -->
@@ -146,6 +175,16 @@ When the value of an `<option>` matches its text content, the attribute can be o
 </select>
 ```
 
+You can give the `<select>` a default value by adding a `selected` attribute to the`<option>` (or options, in the case of `<select multiple>`) that should be initially selected. If the `<select>` is part of a form, it will revert to that selection when the form is reset. Note that for the initial render the value of the binding takes precedence if it's not `undefined`.
+
+```svelte
+<select bind:value={selected}>
+	<option value={a}>a</option>
+	<option value={b} selected>b</option>
+	<option value={c}>c</option>
+</select>
+```
+
 ## `<audio>`
 
 `<audio>` elements have their own set of bindings — five two-way ones...

documentation/docs/03-template-syntax/11-bind.md

@@ -0,0 +1,82 @@
+---
+title: <svelte:boundary>
+---
+
+```svelte
+<svelte:boundary onerror={handler}>...</svelte:boundary>
+```
+
+> [!NOTE]
+> This feature was added in 5.3.0
+
+Boundaries allow you to guard against errors in part of your app from breaking the app as a whole, and to recover from those errors.
+
+If an error occurs while rendering or updating the children of a `<svelte:boundary>`, or running any [`$effect`]($effect) functions contained therein, the contents will be removed.
+
+Errors occurring outside the rendering process (for example, in event handlers) are _not_ caught by error boundaries.
+
+## Properties
+
+For the boundary to do anything, one or both of `failed` and `onerror` must be provided.
+
+### `failed`
+
+If a `failed` snippet is provided, it will be rendered with the error that was thrown, and a `reset` function that recreates the contents ([demo](/playground/hello-world#H4sIAAAAAAAAE3VRy26DMBD8lS2tFCIh6JkAUlWp39Cq9EBg06CAbdlLArL87zWGKk8ORnhmd3ZnrD1WtOjFXqKO2BDGW96xqpBD5gXerm5QefG39mgQY9EIWHxueRMinLosti0UPsJLzggZKTeilLWgLGc51a3gkuCjKQ7DO7cXZotgJ3kLqzC6hmex1SZnSXTWYHcrj8LJjWTk0PHoZ8VqIdCOKayPykcpuQxAokJaG1dGybYj4gw4K5u6PKTasSbjXKgnIDlA8VvUdo-pzonraBY2bsH7HAl78mKSHZpgIcuHjq9jXSpZSLixRlveKYQUXhQVhL6GPobXAAb7BbNeyvNUs4qfRg3OnELLj5hqH9eQZqCnoBwR9lYcQxuVXeBzc8kMF8yXY4yNJ5oGiUzP_aaf_waTRGJib5_Ad3P_vbCuaYxzeNpbU0eUMPAOKh7Yw1YErgtoXyuYlPLzc10_xo_5A91zkQL_AgAA)):
+
+```svelte
+<svelte:boundary>
+	<FlakyComponent />
+
+	{#snippet failed(error, reset)}
+		<button onclick={reset}>oops! try again</button>
+	{/snippet}
+</svelte:boundary>
+```
+
+> [!NOTE]
+> As with [snippets passed to components](snippet#Passing-snippets-to-components), the `failed` snippet can be passed explicitly as a property...
+>
+> ```svelte
+> <svelte:boundary {failed}>...</svelte:boundary>
+> ```
+>
+> ...or implicitly by declaring it directly inside the boundary, as in the example above.
+
+### `onerror`
+
+If an `onerror` function is provided, it will be called with the same two `error` and `reset` arguments. This is useful for tracking the error with an error reporting service...
+
+```svelte
+<svelte:boundary onerror={(e) => report(e)}>
+	...
+</svelte:boundary>
+```
+
+...or using `error` and `reset` outside the boundary itself:
+
+```svelte
+<script>
+	let error = $state(null);
+	let reset = $state(() => {});
+
+	function onerror(e, r) {
+		error = e;
+		reset = r;
+	}
+</script>
+
+<svelte:boundary {onerror}>
+	<FlakyComponent />
+</svelte:boundary>
+
+{#if error}
+	<button onclick={() => {
+		error = null;
+		reset();
+	}}>
+		oops! try again
+	</button>
+{/if}
+```
+
+If an error occurs inside the `onerror` function (or if you rethrow the error), it will be handled by a parent boundary if such exists.

documentation/docs/05-special-elements/01-svelte-boundary.md

@@ -49,7 +49,7 @@ export const userState = $state({
 ```svelte
 <!--- file: App.svelte --->
 <script>
-	import { userState } from './state.svelte';
+	import { userState } from './state.svelte.js';
 </script>
 
 <p>User name: {userState.name}</p>