From 7da1109f573ef4f92436194558f5fda4cf67e184 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Tue, 22 Oct 2024 00:28:04 -0400
Subject: [PATCH] more docs stuff

---
 .../docs/03-template-syntax/11-use.md         | 114 +++----
 .../docs/03-template-syntax/12-transition.md  | 302 ++----------------
 .../docs/03-template-syntax/13-in-and-out.md  |   8 +-
 .../docs/03-template-syntax/14-animate.md     | 115 ++++++-
 4 files changed, 199 insertions(+), 340 deletions(-)

diff --git a/documentation/docs/03-template-syntax/11-use.md b/documentation/docs/03-template-syntax/11-use.md
index 8b030f2c67..ff50e38cf2 100644
--- a/documentation/docs/03-template-syntax/11-use.md
+++ b/documentation/docs/03-template-syntax/11-use.md
@@ -2,102 +2,80 @@
 title: use:
 ---
 
-- template syntax
-- how to write
-- typings
-- adjust so that `$effect` is used instead of update/destroy?
-
-```svelte
-<!--- copy: false --->
-use:action
-```
-
-```svelte
-<!--- copy: false --->
-use:action={parameters}
-```
-
-```ts
-/// copy: false
-// @noErrors
-action = (node: HTMLElement, parameters: any) => {
-	update?: (parameters: any) => void,
-	destroy?: () => void
-}
-```
-
-Actions are functions that are called when an element is created. They can return an object with a `destroy` method that is called after the element is unmounted:
+Actions are functions that are called when an element is mounted. They are added with the `use:` directive, and will typically use an `$effect` so that they can reset any state when the element is unmounted:
 
 ```svelte
 <!--- file: App.svelte --->
 <script>
-	/** @type {import('svelte/action').Action}  */
-	function foo(node) {
+	/** @type {import('svelte/action').Action} */
+	function myaction(node) {
 		// the node has been mounted in the DOM
 
-		return {
-			destroy() {
-				// the node has been removed from the DOM
-			}
-		};
+		$effect(() => {
+			// setup goes here
+
+			return () => {
+				// teardown goes here
+			};
+		});
 	}
 </script>
 
-<div use:foo />
+<div use:myaction>...</div>
 ```
 
-An action can have a parameter. If the returned value has an `update` method, it will be called immediately after Svelte has applied updates to the markup whenever that parameter changes.
-
-> [!NOTE] Don't worry that we're redeclaring the `foo` function for every component instance — Svelte will hoist any functions that don't depend on local state out of the component definition.
+An action can be called with an argument:
 
 ```svelte
 <!--- file: App.svelte --->
 <script>
-	/** @type {string} */
-	export let bar;
-
-	/** @type {import('svelte/action').Action<HTMLElement, string>}  */
-	function foo(node, bar) {
-		// the node has been mounted in the DOM
-
-		return {
-			update(bar) {
-				// the value of `bar` has changed
-			},
-
-			destroy() {
-				// the node has been removed from the DOM
-			}
-		};
+	/** @type {import('svelte/action').Action} */
+	function myaction(node, +++data+++) {
+		// ...
 	}
 </script>
 
-<div use:foo={bar} />
+<div use:myaction={+++data+++}>...</div>
 ```
 
-## Attributes
+The action is only called once (but not during server-side rendering) — it will _not_ run again if the argument changes.
+
+> [!LEGACY]
+> Prior to the `$effect` rune, actions could return an object with `update` and `destroy` methods, where `update` would be called with the latest value of the argument if it changed. Using effects is preferred.
 
-Sometimes actions emit custom events and apply custom attributes to the element they are applied to. To support this, actions typed with `Action` or `ActionReturn` type can have a last parameter, `Attributes`:
+## Typing
+
+The `Action` interface receives three optional type arguments — a node type (which can be `Element`, if the action applies to everything), a parameter, and any custom event handlers created by the action.:
 
 ```svelte
 <!--- file: App.svelte --->
 <script>
+	import { on } from 'svelte/events';
+
 	/**
-	 * @type {import('svelte/action').Action<HTMLDivElement, { prop: any }, { 'on:emit': (e: CustomEvent<string>) => void }>}
+	 * @type {import('svelte/action').Action<
+	 * 	HTMLDivElement,
+	 * 	null,
+	 * 	{
+	 * 		onswiperight: (e: CustomEvent) => void;
+	 * 		onswipeleft: (e: CustomEvent) => void;
+	 * 		// ...
+	 * }>}
 	 */
-	function foo(node, { prop }) {
-		// the node has been mounted in the DOM
-
-		//...LOGIC
-		node.dispatchEvent(new CustomEvent('emit', { detail: 'hello' }));
-
-		return {
-			destroy() {
-				// the node has been removed from the DOM
-			}
-		};
+	function gestures(node) {
+		$effect(() => {
+			// ...
+			node.dispatchEvent(new CustomEvent('swipeleft'));
+
+			// ...
+			node.dispatchEvent(new CustomEvent('swiperight'));
+		});
 	}
 </script>
 
-<div use:foo={{ prop: 'someValue' }} onemit={handleEmit} />
+<div
+	use:gestures
+	onswipeleft={next}
+	onswiperight={prev}
+>...</div>
 ```
diff --git a/documentation/docs/03-template-syntax/12-transition.md b/documentation/docs/03-template-syntax/12-transition.md
index 114d4d9780..51f1008209 100644
--- a/documentation/docs/03-template-syntax/12-transition.md
+++ b/documentation/docs/03-template-syntax/12-transition.md
@@ -2,70 +2,31 @@
 title: transition:
 ---
 
-- how to use (template syntax)
-- when to use
-- global vs local
-- easing & motion
-- mention imports
-- key block
+A _transition_ is triggered by an element entering or leaving the DOM as a result of a state change.
 
-Svelte provides different techniques and syntax for incorporating motion into your Svelte projects.
+When a block (such as an `{#if ...}` block) is transitioning out, all elements inside it, including those that do not have their own transitions, are kept in the DOM until every transition in the block has been completed.
 
-## transition:_fn_
-
-```svelte
-<!--- copy: false --->
-transition:fn
-```
-
-```svelte
-<!--- copy: false --->
-transition:fn={params}
-```
-
-```svelte
-<!--- copy: false --->
-transition:fn|global
-```
+The `transition:` directive indicates a _bidirectional_ transition, which means it can be smoothly reversed while the transition is in progress.
 
 ```svelte
-<!--- copy: false --->
-transition:fn|global={params}
-```
+<script>
+	+++import { fade } from 'svelte/transition';+++
 
-```svelte
-<!--- copy: false --->
-transition:fn|local
-```
+	let visible = $state(false);
+</script>
 
-```svelte
-<!--- copy: false --->
-transition:fn|local={params}
-```
+<button onclick={() => visible = !visible}>toggle</button>
 
-```js
-/// copy: false
-// @noErrors
-transition = (node: HTMLElement, params: any, options: { direction: 'in' | 'out' | 'both' }) => {
-	delay?: number,
-	duration?: number,
-	easing?: (t: number) => number,
-	css?: (t: number, u: number) => string,
-	tick?: (t: number, u: number) => void
-}
+{#if visible}
+	<div +++transition:fade+++>fades in and out</div>
+{/if}
 ```
 
-A transition is triggered by an element entering or leaving the DOM as a result of a state change.
+## Built-in transitions
 
-When a block is transitioning out, all elements inside the block, including those that do not have their own transitions, are kept in the DOM until every transition in the block has been completed.
+A selection of built-in transitions can be imported from the [`svelte/transition`](svelte-transition) module.
 
-The `transition:` directive indicates a _bidirectional_ transition, which means it can be smoothly reversed while the transition is in progress.
-
-```svelte
-{#if visible}
-	<div transition:fade>fades in and out</div>
-{/if}
-```
+## Local vs global
 
 Transitions are local by default. Local transitions only play when the block they belong to is created or destroyed, _not_ when parent blocks are created or destroyed.
 
@@ -79,8 +40,6 @@ Transitions are local by default. Local transitions only play when the block the
 {/if}
 ```
 
-> [!NOTE] By default intro transitions will not play on first render. You can modify this behaviour by setting `intro: true` when you [create a component](imperative-component-api) and marking the transition as `global`.
-
 ## Transition parameters
 
 Transitions can have parameters.
@@ -95,7 +54,19 @@ Transitions can have parameters.
 
 ## Custom transition functions
 
-Transitions can use custom functions. If the returned object has a `css` function, Svelte will create a CSS animation that plays on the element.
+```js
+/// copy: false
+// @noErrors
+transition = (node: HTMLElement, params: any, options: { direction: 'in' | 'out' | 'both' }) => {
+	delay?: number,
+	duration?: number,
+	easing?: (t: number) => number,
+	css?: (t: number, u: number) => string,
+	tick?: (t: number, u: number) => void
+}
+```
+
+Transitions can use custom functions. If the returned object has a `css` function, Svelte will generate keyframes for a [web animation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).
 
 The `t` argument passed to `css` is a value between `0` and `1` after the `easing` function has been applied. _In_ transitions run from `0` to `1`, _out_ transitions run from `1` to `0` — in other words, `1` is the element's natural state, as though no transition had been applied. The `u` argument is equal to `1 - t`.
 
@@ -132,7 +103,7 @@ The function is called repeatedly _before_ the transition begins, with different
 
 A custom transition function can also return a `tick` function, which is called _during_ the transition with the same `t` and `u` arguments.
 
-> [!NOTE] If it's possible to use `css` instead of `tick`, do so — CSS animations can run off the main thread, preventing jank on slower devices.
+> [!NOTE] If it's possible to use `css` instead of `tick`, do so — web animations can run off the main thread, preventing jank on slower devices.
 
 ```svelte
 <!--- file: App.svelte --->
@@ -189,222 +160,13 @@ An element with transitions will dispatch the following events in addition to an
 {#if visible}
 	<p
 		transition:fly={{ y: 200, duration: 2000 }}
-		on:introstart={() => (status = 'intro started')}
-		on:outrostart={() => (status = 'outro started')}
-		on:introend={() => (status = 'intro ended')}
-		on:outroend={() => (status = 'outro ended')}
+		onintrostart={() => (status = 'intro started')}
+		onoutrostart={() => (status = 'outro started')}
+		onintroend={() => (status = 'intro ended')}
+		onoutroend={() => (status = 'outro ended')}
 	>
 		Flies in and out
 	</p>
 {/if}
 ```
 
-## in:_fn_/out:_fn_
-
-```svelte
-<!--- copy: false --->
-in:fn
-```
-
-```svelte
-<!--- copy: false --->
-in:fn={params}
-```
-
-```svelte
-<!--- copy: false --->
-in:fn|global
-```
-
-```svelte
-<!--- copy: false --->
-in:fn|global={params}
-```
-
-```svelte
-<!--- copy: false --->
-in:fn|local
-```
-
-```svelte
-<!--- copy: false --->
-in:fn|local={params}
-```
-
-```svelte
-<!--- copy: false --->
-out:fn
-```
-
-```svelte
-<!--- copy: false --->
-out:fn={params}
-```
-
-```svelte
-<!--- copy: false --->
-out:fn|global
-```
-
-```svelte
-<!--- copy: false --->
-out:fn|global={params}
-```
-
-```svelte
-<!--- copy: false --->
-out:fn|local
-```
-
-```svelte
-<!--- copy: false --->
-out:fn|local={params}
-```
-
-Similar to `transition:`, but only applies to elements entering (`in:`) or leaving (`out:`) the DOM.
-
-Unlike with `transition:`, transitions applied with `in:` and `out:` are not bidirectional — an in transition will continue to 'play' alongside the out transition, rather than reversing, if the block is outroed while the transition is in progress. If an out transition is aborted, transitions will restart from scratch.
-
-```svelte
-{#if visible}
-	<div in:fly out:fade>flies in, fades out</div>
-{/if}
-```
-
-## animate:_fn_
-
-```svelte
-<!--- copy: false --->
-animate:name
-```
-
-```svelte
-<!--- copy: false --->
-animate:name={params}
-```
-
-```js
-/// copy: false
-// @noErrors
-animation = (node: HTMLElement, { from: DOMRect, to: DOMRect } , params: any) => {
-	delay?: number,
-	duration?: number,
-	easing?: (t: number) => number,
-	css?: (t: number, u: number) => string,
-	tick?: (t: number, u: number) => void
-}
-```
-
-```ts
-/// copy: false
-// @noErrors
-DOMRect {
-	bottom: number,
-	height: number,
-	​​left: number,
-	right: number,
-	​top: number,
-	width: number,
-	x: number,
-	y: number
-}
-```
-
-An animation is triggered when the contents of a [keyed each block](each) are re-ordered. Animations do not run when an element is added or removed, only when the index of an existing data item within the each block changes. Animate directives must be on an element that is an _immediate_ child of a keyed each block.
-
-Animations can be used with Svelte's [built-in animation functions](svelte-animate) or [custom animation functions](#Custom-animation-functions).
-
-```svelte
-<!-- When `list` is reordered the animation will run-->
-{#each list as item, index (item)}
-	<li animate:flip>{item}</li>
-{/each}
-```
-
-## Animation Parameters
-
-As with actions and transitions, animations can have parameters.
-
-(The double `{{curlies}}` aren't a special syntax; this is an object literal inside an expression tag.)
-
-```svelte
-{#each list as item, index (item)}
-	<li animate:flip={{ delay: 500 }}>{item}</li>
-{/each}
-```
-
-## Custom animation functions
-
-Animations can use custom functions that provide the `node`, an `animation` object and any `parameters` as arguments. The `animation` parameter is an object containing `from` and `to` properties each containing a [DOMRect](https://developer.mozilla.org/en-US/docs/Web/API/DOMRect#Properties) describing the geometry of the element in its `start` and `end` positions. The `from` property is the DOMRect of the element in its starting position, and the `to` property is the DOMRect of the element in its final position after the list has been reordered and the DOM updated.
-
-If the returned object has a `css` method, Svelte will create a CSS animation that plays on the element.
-
-The `t` argument passed to `css` is a value that goes from `0` and `1` after the `easing` function has been applied. The `u` argument is equal to `1 - t`.
-
-The function is called repeatedly _before_ the animation begins, with different `t` and `u` arguments.
-
-<!-- TODO: Types -->
-
-```svelte
-<!--- file: App.svelte --->
-<script>
-	import { cubicOut } from 'svelte/easing';
-
-	/**
-	 * @param {HTMLElement} node
-	 * @param {{ from: DOMRect; to: DOMRect }} states
-	 * @param {any} params
-	 */
-	function whizz(node, { from, to }, params) {
-		const dx = from.left - to.left;
-		const dy = from.top - to.top;
-
-		const d = Math.sqrt(dx * dx + dy * dy);
-
-		return {
-			delay: 0,
-			duration: Math.sqrt(d) * 120,
-			easing: cubicOut,
-			css: (t, u) => `transform: translate(${u * dx}px, ${u * dy}px) rotate(${t * 360}deg);`
-		};
-	}
-</script>
-
-{#each list as item, index (item)}
-	<div animate:whizz>{item}</div>
-{/each}
-```
-
-A custom animation function can also return a `tick` function, which is called _during_ the animation with the same `t` and `u` arguments.
-
-> [!NOTE] If it's possible to use `css` instead of `tick`, do so — CSS animations can run off the main thread, preventing jank on slower devices.
-
-```svelte
-<!--- file: App.svelte --->
-<script>
-	import { cubicOut } from 'svelte/easing';
-
-	/**
-	 * @param {HTMLElement} node
-	 * @param {{ from: DOMRect; to: DOMRect }} states
-	 * @param {any} params
-	 */
-	function whizz(node, { from, to }, params) {
-		const dx = from.left - to.left;
-		const dy = from.top - to.top;
-
-		const d = Math.sqrt(dx * dx + dy * dy);
-
-		return {
-			delay: 0,
-			duration: Math.sqrt(d) * 120,
-			easing: cubicOut,
-			tick: (t, u) => Object.assign(node.style, { color: t > 0.5 ? 'Pink' : 'Blue' })
-		};
-	}
-</script>
-
-{#each list as item, index (item)}
-	<div animate:whizz>{item}</div>
-{/each}
-```
diff --git a/documentation/docs/03-template-syntax/13-in-and-out.md b/documentation/docs/03-template-syntax/13-in-and-out.md
index a6e9338f82..feb5aa84c5 100644
--- a/documentation/docs/03-template-syntax/13-in-and-out.md
+++ b/documentation/docs/03-template-syntax/13-in-and-out.md
@@ -2,4 +2,10 @@
 title: in: and out:
 ---
 
-Coming soon!
+The `in:` and `out:` directives are identical to [`transition:`](transition), except that the resulting transitions are not bidirectional — an `in` transition will continue to 'play' alongside the `out` transition, rather than reversing, if the block is outroed while the transition is in progress. If an out transition is aborted, transitions will restart from scratch.
+
+```svelte
+{#if visible}
+	<div in:fly out:fade>flies in, fades out</div>
+{/if}
+```
diff --git a/documentation/docs/03-template-syntax/14-animate.md b/documentation/docs/03-template-syntax/14-animate.md
index 03af0ec821..583936be3b 100644
--- a/documentation/docs/03-template-syntax/14-animate.md
+++ b/documentation/docs/03-template-syntax/14-animate.md
@@ -2,4 +2,117 @@
 title: animate:
 ---
 
-Coming soon!
+
+
+
+An animation is triggered when the contents of a [keyed each block](each#Keyed-each-blocks) are re-ordered. Animations do not run when an element is added or removed, only when the index of an existing data item within the each block changes. Animate directives must be on an element that is an _immediate_ child of a keyed each block.
+
+Animations can be used with Svelte's [built-in animation functions](svelte-animate) or [custom animation functions](#Custom-animation-functions).
+
+```svelte
+<!-- When `list` is reordered the animation will run-->
+{#each list as item, index (item)}
+	<li animate:flip>{item}</li>
+{/each}
+```
+
+## Animation Parameters
+
+As with actions and transitions, animations can have parameters.
+
+(The double `{{curlies}}` aren't a special syntax; this is an object literal inside an expression tag.)
+
+```svelte
+{#each list as item, index (item)}
+	<li animate:flip={{ delay: 500 }}>{item}</li>
+{/each}
+```
+
+## Custom animation functions
+
+```js
+/// copy: false
+// @noErrors
+animation = (node: HTMLElement, { from: DOMRect, to: DOMRect } , params: any) => {
+	delay?: number,
+	duration?: number,
+	easing?: (t: number) => number,
+	css?: (t: number, u: number) => string,
+	tick?: (t: number, u: number) => void
+}
+```
+
+Animations can use custom functions that provide the `node`, an `animation` object and any `parameters` as arguments. The `animation` parameter is an object containing `from` and `to` properties each containing a [DOMRect](https://developer.mozilla.org/en-US/docs/Web/API/DOMRect#Properties) describing the geometry of the element in its `start` and `end` positions. The `from` property is the DOMRect of the element in its starting position, and the `to` property is the DOMRect of the element in its final position after the list has been reordered and the DOM updated.
+
+If the returned object has a `css` method, Svelte will create a [web animation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) that plays on the element.
+
+The `t` argument passed to `css` is a value that goes from `0` and `1` after the `easing` function has been applied. The `u` argument is equal to `1 - t`.
+
+The function is called repeatedly _before_ the animation begins, with different `t` and `u` arguments.
+
+<!-- TODO: Types -->
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	import { cubicOut } from 'svelte/easing';
+
+	/**
+	 * @param {HTMLElement} node
+	 * @param {{ from: DOMRect; to: DOMRect }} states
+	 * @param {any} params
+	 */
+	function whizz(node, { from, to }, params) {
+		const dx = from.left - to.left;
+		const dy = from.top - to.top;
+
+		const d = Math.sqrt(dx * dx + dy * dy);
+
+		return {
+			delay: 0,
+			duration: Math.sqrt(d) * 120,
+			easing: cubicOut,
+			css: (t, u) => `transform: translate(${u * dx}px, ${u * dy}px) rotate(${t * 360}deg);`
+		};
+	}
+</script>
+
+{#each list as item, index (item)}
+	<div animate:whizz>{item}</div>
+{/each}
+```
+
+A custom animation function can also return a `tick` function, which is called _during_ the animation with the same `t` and `u` arguments.
+
+> [!NOTE] If it's possible to use `css` instead of `tick`, do so — web animations can run off the main thread, preventing jank on slower devices.
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	import { cubicOut } from 'svelte/easing';
+
+	/**
+	 * @param {HTMLElement} node
+	 * @param {{ from: DOMRect; to: DOMRect }} states
+	 * @param {any} params
+	 */
+	function whizz(node, { from, to }, params) {
+		const dx = from.left - to.left;
+		const dy = from.top - to.top;
+
+		const d = Math.sqrt(dx * dx + dy * dy);
+
+		return {
+			delay: 0,
+			duration: Math.sqrt(d) * 120,
+			easing: cubicOut,
+			tick: (t, u) => Object.assign(node.style, { color: t > 0.5 ? 'Pink' : 'Blue' })
+		};
+	}
+</script>
+
+{#each list as item, index (item)}
+	<div animate:whizz>{item}</div>
+{/each}
+```
+