From 53a2c49a478c23de71ed33f8728570a49d79934d Mon Sep 17 00:00:00 2001
From: Rich-Harris <1162160+Rich-Harris@users.noreply.github.com>
Date: Thu, 31 Oct 2024 18:53:38 +0000
Subject: [PATCH] sync svelte docs

---
 .../content/docs/svelte/02-runes/05-$props.md | 89 +++++++++++++++++--
 .../svelte/03-template-syntax/05-await.md     |  9 ++
 .../svelte/07-misc/07-v5-migration-guide.md   |  2 +-
 3 files changed, 90 insertions(+), 10 deletions(-)

diff --git a/apps/svelte.dev/content/docs/svelte/02-runes/05-$props.md b/apps/svelte.dev/content/docs/svelte/02-runes/05-$props.md
index 8e3dcfb341..58e9b36f8e 100644
--- a/apps/svelte.dev/content/docs/svelte/02-runes/05-$props.md
+++ b/apps/svelte.dev/content/docs/svelte/02-runes/05-$props.md
@@ -5,29 +5,29 @@ title: $props
 The inputs to a component are referred to as _props_, which is short for _properties_. You pass props to components just like you pass attributes to elements:
 
 ```svelte
+<!--- file: App.svelte --->
 <script>
 	import MyComponent from './MyComponent.svelte';
 </script>
 
-/// file: App.svelte
 <MyComponent adjective="cool" />
 ```
 
 On the other side, inside `MyComponent.svelte`, we can receive props with the `$props` rune...
 
 ```svelte
+<!--- file: MyComponent.svelte --->
 <script>
 	let props = $props();
 </script>
 
-/// file: MyComponent.svelte
 <p>this component is {props.adjective}</p>
 ```
 
 ...though more commonly, you'll [_destructure_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) your props:
 
 ```svelte
-/// file: MyComponent.svelte
+<!--- file: MyComponent.svelte --->
 <script>
 	let +++{ adjective }+++ = $props();
 </script>
@@ -40,11 +40,10 @@ On the other side, inside `MyComponent.svelte`, we can receive props with the `$
 Destructuring allows us to declare fallback values, which are used if the parent component does not set a given prop:
 
 ```js
-/// file: MyComponent.svelte
 let { adjective = 'happy' } = $props();
 ```
 
-> [!NOTE] Fallback values are not turned into reactive state proxies.
+> [!NOTE] Fallback values are not turned into reactive state proxies (see [Updating props](#Updating-props) for more info)
 
 ## Renaming props
 
@@ -66,9 +65,8 @@ let { a, b, c, ...others } = $props();
 
 References to a prop inside a component update when the prop itself updates — when `count` changes in `App.svelte`, it will also change inside `Child.svelte`. But the child component is able to temporarily override the prop value, which can be useful for unsaved ephemeral state ([demo](/playground/untitled#H4sIAAAAAAAAE6WQ0WrDMAxFf0WIQR0Wmu3VTQJln7HsIfVcZubIxlbGRvC_DzuBraN92qPula50tODZWB1RPi_IX16jLALWSOOUq6P3-_ihLWftNEZ9TVeOWBNHlNhGFYznfqCBzeRdYHh6M_YVzsFNsNs3pdpGd4eBcqPVDMrNxNDBXeSRtXioDgO1zU8ataeZ2RE4Utao924RFXQ9iHXwvoPHKpW1xY4g_Bg0cSVhKS0p560Za95612ZC02ONrD8ZJYdZp_rGQ37ff_mSP86Np2TWZaNNmdcH56P4P67K66_SXoK9pG-5dF5Z9QEAAA==)):
 
-<!-- prettier-ignore -->
 ```svelte
-/// file: App.svelte
+<!--- file: App.svelte --->
 <script>
 	import Child from './Child.svelte';
 
@@ -82,9 +80,8 @@ References to a prop inside a component update when the prop itself updates —
 <Child {count} />
 ```
 
-<!-- prettier-ignore -->
 ```svelte
-/// file: Child.svelte
+<!--- file: Child.svelte --->
 <script>
 	let { count } = $props();
 </script>
@@ -94,6 +91,80 @@ References to a prop inside a component update when the prop itself updates —
 </button>
 ```
 
+While you can temporarily _reassign_ props, you should not _mutate_ props unless they are [bindable]($bindable).
+
+If the prop is a regular object, the mutation will have no effect ([demo](/playground/untitled#H4sIAAAAAAAAE3WQwU7DMBBEf2W1QmorQgJXk0RC3PkBwiExG9WQrC17U4Es_ztKUkQp9OjxzM7bjcjtSKjwyfKNp1aLORA4b13ADHszUED1HFE-3eyaBcy-Mw_O5eFAg8xa1wb6T9eWhVgCKiyD9sZJ3XAjZnTWCzzuzfAKvbcjbPJieR2jm_uGy-InweXqtd0baaliBG0nFgW3kBIUNWYo9CGoxE-UsgvIpw2_oc9-LmAPJBCPDJCggqvlVtvdH9puErEMlvVg9HsVtzuoaojzkKKAfRuALVDfk5ZZW0fmy05wXcFdwyktlUs-KIinljTXrRVnm7-kL9dYLVbUAQAA)):
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	import Child from './Child.svelte';
+</script>
+
+<Child object={{ count: 0 }} />
+```
+
+```svelte
+<!--- file: Child.svelte --->
+<script>
+	let { object } = $props();
+</script>
+
+<button onclick={() => {
+	// has no effect
+	object.count += 1
+}}>
+	clicks: {object.count}
+</button>
+```
+
+If the prop is a reactive state proxy, however, then mutations _will_ have an effect but you will see an [`ownership_invalid_mutation`](runtime-warnings#Client-warnings-ownership_invalid_mutation) warning, because the component is mutating state that does not 'belong' to it ([demo](/playground/untitled#H4sIAAAAAAAAE3WR0U7DMAxFf8VESBuiauG1WycheOEbKA9p67FA6kSNszJV-XeUZhMw2GN8r-1znUmQ7FGU4pn2UqsOes-SlSGRia3S6ET5Mgk-2OiJBZGdOh6szd0eNcdaIx3-V28NMRI7UYq1awdleVNTzaq3ZmB43CndwXYwPSzyYn4dWxermqJRI4Np3rFlqODasWRcTtAaT1zCHYSbVU3r4nsyrdPMKTUFKDYiE4yfLEoePIbsQpqfy3_nOVMuJIqg0wk1RFg7GOuWfwEbz2wIDLVatR_VtLyBagNTHFIUMCqtoZXeIfAOU1JoUJsR2IC3nWTMjt7GM4yKdyBhlAMpesvhydCC0y_i0ZagHByMh26WzUhXUUxKnpbcVnBfUwhznJnNlac7JkuIURL-2VVfwxflyrWcSQIAAA==)):
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	import Child from './Child.svelte';
+
+	let object = $state({count: 0});
+</script>
+
+<Child {object} />
+```
+
+```svelte
+<!--- file: Child.svelte --->
+<script>
+	let { object } = $props();
+</script>
+
+<button onclick={() => {
+	// will cause the count below to update,
+	// but with a warning. Don't mutate
+	// objects you don't own!
+	object.count += 1
+}}>
+	clicks: {object.count}
+</button>
+```
+
+The fallback value of a prop not declared with `$bindable` is left untouched — it is not turned into a reactive state proxy — meaning mutations will not cause updates ([demo](/playground/untitled#H4sIAAAAAAAAE3WQwU7DMBBEf2VkIbUVoYFraCIh7vwA4eC4G9Wta1vxpgJZ_nfkBEQp9OjxzOzTRGHlkUQlXpy9G0gq1idCL43ppDrAD84HUYheGwqieo2CP3y2Z0EU3-En79fhRIaz1slA_-nKWSbLQVRiE9SgPTetbVkfvRsYzztttugHd8RiXU6vr-jisbWb8idhN7O3bEQhmN5ZVDyMlIorcOddv_Eufq4AGmJEuG5PilEjQrnRcoV7JCTUuJlGWq7-YHYjs7NwVhmtDnVcrlA3iLmzLLGTAdaB-j736h68Oxv-JM1I0AFjoG1OzPfX023c1nhobUoT39QeKsRzS8owM8DFTG_pE6dcVl70AQAA))
+
+```svelte
+<!--- file: Child.svelte --->
+<script>
+	let { object = { count: 0 } } = $props();
+</script>
+
+<button onclick={() => {
+	// has no effect if the fallback value is used
+	object.count += 1
+}}>
+	clicks: {object.count}
+</button>
+```
+
+In summary: don't mutate props. Either use callback props to communicate changes, or — if parent and child should share the same object — use the [`$bindable`]($bindable) rune.
+
 ## Type safety
 
 You can add type safety to your components by annotating your props, as you would with any other variable declaration. In TypeScript that might look like this...
diff --git a/apps/svelte.dev/content/docs/svelte/03-template-syntax/05-await.md b/apps/svelte.dev/content/docs/svelte/03-template-syntax/05-await.md
index 6f365179e4..842b3c7e32 100644
--- a/apps/svelte.dev/content/docs/svelte/03-template-syntax/05-await.md
+++ b/apps/svelte.dev/content/docs/svelte/03-template-syntax/05-await.md
@@ -68,3 +68,12 @@ Similarly, if you only want to show the error state, you can omit the `then` blo
 	<p>The error is {error}</p>
 {/await}
 ```
+
+> [!NOTE] You can use `#await` with [`import(...)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) to render components lazily:
+>
+> ```svelte
+> {#await import('./Component.svelte') then { default: Component }}
+> 	<Component />
+> {/await}
+> ```
+
diff --git a/apps/svelte.dev/content/docs/svelte/07-misc/07-v5-migration-guide.md b/apps/svelte.dev/content/docs/svelte/07-misc/07-v5-migration-guide.md
index 1624755a6b..093ec5b86b 100644
--- a/apps/svelte.dev/content/docs/svelte/07-misc/07-v5-migration-guide.md
+++ b/apps/svelte.dev/content/docs/svelte/07-misc/07-v5-migration-guide.md
@@ -376,7 +376,7 @@ If you wanted multiple UI placeholders, you had to use named slots. In Svelte 5,
 </main>
 
 <footer>
-	---<slot name="header" />---
+	---<slot name="footer" />---
 	+++{@render footer()}+++
 </footer>
 ```