more docs stuff

Author: Rich-Harris

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>
 ```