From bdc61c7822b91577979f4a8b42fec5e71806e0a3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20D=C4=9Bdi=C4=8D?= <developer@dedic.eu>
Date: Sat, 21 Dec 2024 13:18:29 +0100
Subject: [PATCH] Expanded svelte/reactivity documentation

---
 .../docs/98-reference/21-svelte-reactivity.md | 81 +++++++++++++++++++
 1 file changed, 81 insertions(+)

diff --git a/documentation/docs/98-reference/21-svelte-reactivity.md b/documentation/docs/98-reference/21-svelte-reactivity.md
index 6857c1dba80d..141c674b6678 100644
--- a/documentation/docs/98-reference/21-svelte-reactivity.md
+++ b/documentation/docs/98-reference/21-svelte-reactivity.md
@@ -22,4 +22,85 @@ Svelte provides reactive versions of various built-ins like `SvelteMap`, `Svelte
 <input bind:value={url.href} />
 ```
 
+The utilities provided in `svelte/reactivity` are automatically reactive with respect to their properties and methods, as seen in the previous example. As such, they don't need to be wrapped in `$state`. However, if a variable is reassigned, it needs to be wrapped in a `$state` in order for this reassignement to be reactive.
+
+```svelte
+<script>
+	import { SvelteURL } from 'svelte/reactivity';
+
+	let url = $state(new SvelteURL('https://example.com/path'));
+</script>
+
+<!-- these are reactive... -->
+Protocol: {url?.protocol ?? "ftp:"}
+<br>
+Hostname: {url?.hostname ?? "svelte.dev"}
+<br>
+Path: {url?.pathname ?? ""}
+
+<hr />
+
+<!-- ...even when reassigning -->
+<button
+	onclick={() => {
+		url = undefined;
+	}}
+>
+	Erase
+</button>
+```
+
+In a similar manner, the values stored inside e.g. `SvelteMap` are not automatically reactive, so if more complex values such as objects are used, they need to be wrapped in a `$state` in order to make their properties reactive as well.
+
+```svelte
+<script>
+	import { SvelteMap } from 'svelte/reactivity';
+
+	const people = new SvelteMap();
+
+	const alice = {name: "Alice", age: 18};
+	people.set("alice", alice);
+
+	const bob = $state({name: "Bob", age: 21});
+	people.set("bob", bob);
+</script>
+
+{#each people.entries() as [id, person] (id)}
+	Name: {person.name}
+	<br>
+	Age: {person.age}
+	<br>
+	<br>
+{/each}
+
+<hr />
+
+<!-- This will NOT propagate reactively -->
+<button
+	onclick={() => {
+		people.get("alice").age++;
+	}}
+>
+	Alice's birthday
+</button>
+
+<!-- This WILL propagate reactively -->
+<button
+	onclick={() => {
+		people.get("bob").age++;
+	}}
+>
+	Bob's birthday
+</button>
+
+<!-- This WILL propagate reactively (but subsequent updates to the object won't) -->
+<button
+	onclick={() => {
+		people.set("carol", {name: "Carol", age: 0});
+	}}
+>
+	Carol was born
+</button>
+```
+
 > MODULE: svelte/reactivity