From b639581ed778fd872bc148152a8b7f776418f87b Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Mon, 21 Oct 2024 22:12:20 -0400
Subject: [PATCH] tweaks

---
 .../03-template-syntax/01-basic-markup.md     |  4 +-
 .../docs/99-legacy/03-legacy-export-let.md    | 51 +++++++++++--------
 .../04-legacy-$$props-and-$$restProps.md      | 30 +++++++++++
 .../docs/99-legacy/04-legacy-$$props.md       | 12 -----
 .../docs/99-legacy/05-legacy-$$restProps.md   | 12 -----
 5 files changed, 63 insertions(+), 46 deletions(-)
 create mode 100644 documentation/docs/99-legacy/04-legacy-$$props-and-$$restProps.md
 delete mode 100644 documentation/docs/99-legacy/04-legacy-$$props.md
 delete mode 100644 documentation/docs/99-legacy/05-legacy-$$restProps.md

diff --git a/documentation/docs/03-template-syntax/01-basic-markup.md b/documentation/docs/03-template-syntax/01-basic-markup.md
index 07b093df87..774ac6ca3e 100644
--- a/documentation/docs/03-template-syntax/01-basic-markup.md
+++ b/documentation/docs/03-template-syntax/01-basic-markup.md
@@ -18,7 +18,7 @@ A lowercase tag, like `<div>`, denotes a regular HTML element. A capitalised tag
 </div>
 ```
 
-## Attributes and props
+## Element attributes
 
 By default, attributes work exactly like their HTML counterparts.
 
@@ -72,6 +72,8 @@ When the attribute name and value match (`name={name}`), they can be replaced wi
 -->
 ```
 
+## Component props
+
 By convention, values passed to components are referred to as _properties_ or _props_ rather than _attributes_, which are a feature of the DOM.
 
 As with elements, `name={name}` can be replaced with the `{name}` shorthand.
diff --git a/documentation/docs/99-legacy/03-legacy-export-let.md b/documentation/docs/99-legacy/03-legacy-export-let.md
index 75ff14d4e1..877e105b1f 100644
--- a/documentation/docs/99-legacy/03-legacy-export-let.md
+++ b/documentation/docs/99-legacy/03-legacy-export-let.md
@@ -2,11 +2,14 @@
 title: export let
 ---
 
-Svelte uses the `export` keyword to mark a variable declaration as a _property_ or _prop_, which means it becomes accessible to consumers of the component (see the section on [attributes and props](/docs/basic-markup#attributes-and-props) for more information).
+In runes mode, [component props](basic-markup#Component-props) are declared with the [`$props`]($props) rune, allowing parent components to pass in data.
+
+In legacy mode, props are marked with the `export` keyword, and can have a default value:
 
 ```svelte
 <script>
 	export let foo;
+	export let bar = 'default value';
 
 	// Values that are passed in as props
 	// are immediately available
@@ -14,38 +17,47 @@ Svelte uses the `export` keyword to mark a variable declaration as a _property_
 </script>
 ```
 
-You can specify a default initial value for a prop. It will be used if the component's consumer doesn't specify the prop on the component (or if its initial value is `undefined`) when instantiating the component. Note that if the values of props are subsequently updated, then any prop whose value is not specified will be set to `undefined` (rather than its initial value).
+The default value is used if it would otherwise be `undefined` when the component is created.
 
-In development mode (see the [compiler options](/docs/svelte-compiler#compile)), a warning will be printed if no default initial value is provided and the consumer does not specify a value. To squelch this warning, ensure that a default initial value is specified, even if it is `undefined`.
+> [!NOTE] Unlike in runes mode, if the parent component changes a prop from a defined value to `undefined`, it does not revert to the initial value.
 
-```svelte
-<script>
-	export let bar = 'optional default initial value';
-	export let baz = undefined;
-</script>
+Props without default values are considered _required_, and Svelte will print a warning during development if no value is provided, which you can squelch by specifying `undefined` as the default value:
+
+```js
+export let foo +++= undefined;+++
 ```
 
-If you export a `const`, `class` or `function`, it is readonly from outside the component. Functions are valid prop values, however, as shown below.
+## Component exports
+
+An exported `const`, `class` or `function` declaration is _not_ considered a prop — instead, it becomes part of the component's API:
 
 ```svelte
-<!--- file: App.svelte --->
+<!--- file: Greeter.svelte--->
 <script>
-	// these are readonly
-	export const thisIs = 'readonly';
-
-	/** @param {string} name */
 	export function greet(name) {
 		alert(`hello ${name}!`);
 	}
+</script>
+```
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	import Greeter from './Greeter.svelte';
 
-	// this is a prop
-	export let format = (n) => n.toFixed(2);
+	let greeter;
 </script>
+
+<Greeter bind:this={greeter} />
+
+<button on:click={() => greeter.greet('world')}>
+	greet
+</button>
 ```
 
-Readonly props can be accessed as properties on the element, tied to the component using [`bind:this` syntax](/docs/component-directives#bind-this).
+## Renaming props
 
-You can use reserved words as prop names.
+The `export` keyword can appear separately from the declaration. This is useful for renaming props, for example in the case of a reserved word:
 
 ```svelte
 <!--- file: App.svelte --->
@@ -58,6 +70,3 @@ You can use reserved words as prop names.
 	export { className as class };
 </script>
 ```
-
-> [!NOTE]
-> In Svelte 5+, use the [`$props`]($props) rune instead
diff --git a/documentation/docs/99-legacy/04-legacy-$$props-and-$$restProps.md b/documentation/docs/99-legacy/04-legacy-$$props-and-$$restProps.md
new file mode 100644
index 0000000000..33cac97035
--- /dev/null
+++ b/documentation/docs/99-legacy/04-legacy-$$props-and-$$restProps.md
@@ -0,0 +1,30 @@
+---
+title: $$props and $$restProps
+---
+
+In runes mode, getting an object containing all the props that were passed in is easy, using the [`$props`]($props) rune.
+
+In legacy mode, we use `$$props` and `$$restProps`:
+
+- `$$props` contains all the props that were passed in, including ones that are not individually declared with the `export` keyword
+- `$$restProps` contains all the props that were passed in _except_ the ones that were individually declared
+
+For example, a `<Button>` component might need to pass along all its props to its own `<button>` element, except the `variant` prop:
+
+```svelte
+<script>
+	export let variant;
+</script>
+
+<button {...$$restProps} class="variant-{variant} {$$props.class ?? ''}">
+	click me
+</button>
+
+<style>
+	.variant-danger {
+		background: red;
+	}
+</style>
+```
+
+In Svelte 3/4 using `$$props` and `$$restProps` creates a modest performance penalty, so they should only be used when needed.
diff --git a/documentation/docs/99-legacy/04-legacy-$$props.md b/documentation/docs/99-legacy/04-legacy-$$props.md
deleted file mode 100644
index 32f64287f0..0000000000
--- a/documentation/docs/99-legacy/04-legacy-$$props.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: $$props
----
-
-`$$props` references all props that are passed to a component, including ones that are not declared with `export`. Using `$$props` will not perform as well as references to a specific prop because changes to any prop will cause Svelte to recheck all usages of `$$props`. But it can be useful in some cases – for example, when you don't know at compile time what props might be passed to a component.
-
-```svelte
-<Widget {...$$props} />
-```
-
-> [!NOTE]
-> In Svelte 5+, this concept is unnecessary as you can use [`let prop = $props()`]($props) instead
diff --git a/documentation/docs/99-legacy/05-legacy-$$restProps.md b/documentation/docs/99-legacy/05-legacy-$$restProps.md
deleted file mode 100644
index db84a91030..0000000000
--- a/documentation/docs/99-legacy/05-legacy-$$restProps.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: $$restProps
----
-
-`$$restProps` contains only the props which are _not_ declared with `export`. It can be used to pass down other unknown attributes to an element in a component. It shares the same performance characteristics compared to specific property access as `$$props`.
-
-```svelte
-<input {...$$restProps} />
-```
-
-> [!NOTE]
-> In Svelte 5+, this concept is unnecessary as you can use [`let { foo, ...rest } = $props()`]($props) instead