From 60722480815a6b49b162c6e935f00ef86a2bdaec Mon Sep 17 00:00:00 2001
From: Ben McCann <322311+benmccann@users.noreply.github.com>
Date: Fri, 19 Aug 2022 17:17:50 -0700
Subject: [PATCH] [docs] clarify reactivity rules

---
 site/content/docs/01-component-format.md | 32 +++++++++++++++++++-----
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/site/content/docs/01-component-format.md b/site/content/docs/01-component-format.md
index 1c64094002..889e432a60 100644
--- a/site/content/docs/01-component-format.md
+++ b/site/content/docs/01-component-format.md
@@ -55,9 +55,7 @@ In development mode (see the [compiler options](/docs#compile-time-svelte-compil
 
 ---
 
-If you export a `const`, `class` or `function`, it is readonly from outside the component. Function *expressions* are valid props, however.
-
-Readonly props can be accessed as properties on the element, tied to the component using [`bind:this` syntax](/docs#template-syntax-component-directives-bind-this).
+If you export a `const`, `class` or `function`, it is readonly from outside the component. Functions are valid prop values, however, as shown below.
 
 ```sv
 <script>
@@ -73,6 +71,8 @@ Readonly props can be accessed as properties on the element, tied to the compone
 </script>
 ```
 
+Readonly props can be accessed as properties on the element, tied to the component using [`bind:this` syntax](/docs#template-syntax-component-directives-bind-this).
+
 ---
 
 You can use reserved words as prop names.
@@ -87,7 +87,7 @@ You can use reserved words as prop names.
 </script>
 ```
 
-#### 2. Assignments are 'reactive'
+#### 2. Assignments cause updates
 
 ---
 
@@ -109,7 +109,7 @@ Update expressions (`count += 1`) and property assignments (`obj.x = y`) have th
 
 ---
 
-Because Svelte's reactivity is based on assignments, using array methods like `.push()` and `.splice()` won't automatically trigger updates. A subsequent assignment is required to trigger the update. This and more details can also be found in the [tutorial](/tutorial/updating-arrays-and-objects).
+Because Svelte's change tracking is based on assignments, using array methods like `.push()` and `.splice()` won't automatically trigger updates. A subsequent assignment is required to trigger the update. This and more details can also be found in the [tutorial](/tutorial/updating-arrays-and-objects).
 
 ```sv
 <script>
@@ -125,15 +125,29 @@ Because Svelte's reactivity is based on assignments, using array methods like `.
 </script>
 ```
 
+---
+
+Svelte's `<script>` blocks are run only when the component is created, so assignments within a `<script>` block are not automatically run again when a prop updates. If you'd like to track changes to a prop, see the next example in the following section.
+
+```sv
+<script>
+	export let person;
+	// this will only set `name` on component creation
+	// it will not update when `person` does
+	let { name } = person;
+</script>
+```
+
 #### 3. `$:` marks a statement as reactive
 
 ---
 
-Any top-level statement (i.e. not inside a block or a function) can be made reactive by prefixing it with the `$:` [JS label syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/label). Reactive statements run immediately before the component updates, whenever the values that they depend on have changed.
+Any top-level statement (i.e. not inside a block or a function) can be made reactive by prefixing it with the `$:` [JS label syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/label). Reactive statements run after other script code and before the component markup is rendered, whenever the values that they depend on have changed.
 
 ```sv
 <script>
 	export let title;
+	export let person
 
 	// this will update `document.title` whenever
 	// the `title` prop changes
@@ -143,6 +157,12 @@ Any top-level statement (i.e. not inside a block or a function) can be made reac
 		console.log(`multiple statements can be combined`);
 		console.log(`the current title is ${title}`);
 	}
+
+	// this will update `name` when 'person' changes
+	$: ({ name } = person);
+
+	// don't do this. it will run before the previous line
+	let name2 = name;
 </script>
 ```