From 62c9fbb63ba6c4aa2baa62e57fe1eec70d941d3c Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Sat, 19 Oct 2024 14:42:55 -0400
Subject: [PATCH] props

---
 .../docs/01-introduction/03-svelte-files.md   |  4 +-
 documentation/docs/02-runes/02-$state.md      |  2 +-
 documentation/docs/02-runes/04-$effect.md     |  4 +-
 documentation/docs/02-runes/05-$props.md      | 91 ++++++++++++++++++-
 4 files changed, 95 insertions(+), 6 deletions(-)

diff --git a/documentation/docs/01-introduction/03-svelte-files.md b/documentation/docs/01-introduction/03-svelte-files.md
index d68bb89126..f534e30fcb 100644
--- a/documentation/docs/01-introduction/03-svelte-files.md
+++ b/documentation/docs/01-introduction/03-svelte-files.md
@@ -37,8 +37,6 @@ In addition to normal JavaScript, you can use _runes_ to declare [component prop
 
 A `<script>` tag with a `module` attribute runs once when the module first evaluates, rather than for each component instance. Variables declared in this block can be referenced elsewhere in the component, but not vice versa.
 
-You can `export` bindings from this block, and they will become exports of the compiled module. You cannot `export default`, since the default export is the component itself.
-
 ```svelte
 <script module>
 	let total = 0;
@@ -50,6 +48,8 @@ You can `export` bindings from this block, and they will become exports of the c
 </script>
 ```
 
+You can `export` bindings from this block, and they will become exports of the compiled module. You cannot `export default`, since the default export is the component itself.
+
 ## `<style>`
 
 CSS inside a `<style>` block will be scoped to that component.
diff --git a/documentation/docs/02-runes/02-$state.md b/documentation/docs/02-runes/02-$state.md
index 7653e3e87a..5c942c0444 100644
--- a/documentation/docs/02-runes/02-$state.md
+++ b/documentation/docs/02-runes/02-$state.md
@@ -97,7 +97,7 @@ let person = $state.raw({
 	age: 49
 });
 
-// this will have no effect (and will throw an error in dev)
+// this will have no effect
 person.age += 1;
 
 // this will work, because we're creating a new person
diff --git a/documentation/docs/02-runes/04-$effect.md b/documentation/docs/02-runes/04-$effect.md
index c81dcbc570..4e665a8d68 100644
--- a/documentation/docs/02-runes/04-$effect.md
+++ b/documentation/docs/02-runes/04-$effect.md
@@ -4,7 +4,7 @@ title: $effect
 
 Effects are what make your application _do things_. When Svelte runs an effect function, it tracks which pieces of state (and derived state) are accessed, and re-runs the function when that state later changes.
 
-Most of the effects in a Svelte app are created by Svelte itself — they're the bits that update the text in `<h1>hello {name}!</h1>` when `name` changes.
+Most of the effects in a Svelte app are created by Svelte itself — they're the bits that update the text in `<h1>hello {name}!</h1>` when `name` changes, for example.
 
 But you can also create your own effects with the `$effect` rune, which is useful when you need to synchronize an external system (whether that's a library, or a `<canvas>` element, or something across a network) with state inside your Svelte app.
 
@@ -68,7 +68,7 @@ You can return a function from `$effect`, which will run immediately before the
 
 `$effect` automatically picks up any reactive values (`$state`, `$derived`, `$props`) that are _synchronously_ read inside its function body and registers them as dependencies. When those dependencies change, the `$effect` schedules a rerun.
 
-Values that are read asynchronously — after an `await` or inside a `setTimeout`, for example — will _not_ be tracked. Here, the canvas will be repainted when `color` changes, but not when `size` changes ([demo](/playground/untitled#H4sIAAAAAAAAE31T246bMBD9lZF3pWSlBEirfaEQqdo_2PatVIpjBrDkGGQPJGnEv1e2IZfVal-wfHzmzJyZ4cIqqdCy9M-F0blDlnqArZjmB3f72XWRHVCRw_bc4me4aDWhJstSlllhZEfbQhekkMDKfwg5PFvihMvX5OXH_CJa1Zrb0-Kpqr5jkiwC48rieuDWQbqgZ6wqFLRcvkC-hYvnkWi1dWqa8ESQTxFRjfQWsOXiWzmr0sSLhEJu3p1YsoJkNUcdZUnN9dagrBu6FVRQHAM10sJRKgUG16bXcGxQ44AGdt7SDkTDdY02iqLHnJVU6hedlWuIp94JW6Tf8oBt_8GdTxlF0b4n0C35ZLBzXb3mmYn3ae6cOW74zj0YVzDNYXRHFt9mprNgHfZSl6mzml8CMoLvTV6wTZIUDEJv5us2iwMtiJRyAKG4tXnhl8O0yhbML0Wm-B7VNlSSSd31BG7z8oIZZ6dgIffAVY_5xdU9Qrz1Bnx8fCfwtZ7v8Qc9j3nB8PqgmMWlHIID6-bkVaPZwDySfWtKNGtquxQ23Qlsq2QJT0KIqb8dL0up6xQ2eIBkAg_c1FI_YqW0neLnFCqFpwmreedJYT7XX8FVOBfwWRhXstZrSXiwKQjUhOZeMIleb5JZfHWn2Yq5pWEpmR7Hv-N_wEqT8hEEAAA=)):
+Values that are read _asynchronously_ — after an `await` or inside a `setTimeout`, for example — will not be tracked. Here, the canvas will be repainted when `color` changes, but not when `size` changes ([demo](/playground/untitled#H4sIAAAAAAAAE31T246bMBD9lZF3pWSlBEirfaEQqdo_2PatVIpjBrDkGGQPJGnEv1e2IZfVal-wfHzmzJyZ4cIqqdCy9M-F0blDlnqArZjmB3f72XWRHVCRw_bc4me4aDWhJstSlllhZEfbQhekkMDKfwg5PFvihMvX5OXH_CJa1Zrb0-Kpqr5jkiwC48rieuDWQbqgZ6wqFLRcvkC-hYvnkWi1dWqa8ESQTxFRjfQWsOXiWzmr0sSLhEJu3p1YsoJkNUcdZUnN9dagrBu6FVRQHAM10sJRKgUG16bXcGxQ44AGdt7SDkTDdY02iqLHnJVU6hedlWuIp94JW6Tf8oBt_8GdTxlF0b4n0C35ZLBzXb3mmYn3ae6cOW74zj0YVzDNYXRHFt9mprNgHfZSl6mzml8CMoLvTV6wTZIUDEJv5us2iwMtiJRyAKG4tXnhl8O0yhbML0Wm-B7VNlSSSd31BG7z8oIZZ6dgIffAVY_5xdU9Qrz1Bnx8fCfwtZ7v8Qc9j3nB8PqgmMWlHIID6-bkVaPZwDySfWtKNGtquxQ23Qlsq2QJT0KIqb8dL0up6xQ2eIBkAg_c1FI_YqW0neLnFCqFpwmreedJYT7XX8FVOBfwWRhXstZrSXiwKQjUhOZeMIleb5JZfHWn2Yq5pWEpmR7Hv-N_wEqT8hEEAAA=)):
 
 ```ts
 // @filename: index.ts
diff --git a/documentation/docs/02-runes/05-$props.md b/documentation/docs/02-runes/05-$props.md
index 1ac90662c7..8ac4e455f9 100644
--- a/documentation/docs/02-runes/05-$props.md
+++ b/documentation/docs/02-runes/05-$props.md
@@ -2,4 +2,93 @@
 title: $props
 ---
 
-Coming soon!
+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
+<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
+<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
+<script>
+	let +++{ adjective }+++ = $props();
+</script>
+
+<p>this component is {+++adjective+++}</p>
+```
+
+## Default values
+
+Destructuring allows us to declare default values, which are used if the parent component does not set a given prop:
+
+```js
+/// file: MyComponent.svelte
+let { adjective = 'happy' } = $props();
+```
+
+## Renaming props
+
+We can also use the destructuring assignment to rename props, which is necessary if they're invalid identifiers, or a JavaScript keyword like `super`:
+
+```js
+let { super: trouper = 'lights are gonna find me' } = $props();
+```
+
+## Rest props
+
+Finally, we can use a _rest property_ to get, well, the rest of the props:
+
+```js
+let { a, b, c, ...others } = $props();
+```
+
+## 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...
+
+```svelte
+<script lang="ts">
+	let { adjective }: { adjective: string } = $props();
+</script>
+```
+
+...while in JSDoc you can do this:
+
+```svelte
+<script>
+	/** @type {{ adjective: string }} */
+	let { adjective } = $props();
+</script>
+```
+
+You can, of course, separate the type declaration from the annotation:
+
+```svelte
+<script lang="ts">
+	interface Props {
+		adjective: string;
+	}
+
+	let { adjective }: Props = $props();
+</script>
+```
+
+Adding types is recommended, as it ensures that people using your component can easily discover which props they should provide.