docs: attachment tutorial (#1690)

* docs: rename action tutorial files -> attachments

* docs: update "The attach tag" tutorial step

* docs: update "Attachment factories" tutorial step

* docs: update "Binding to component instances" link and example

Previously referenced the Actions tutorial example; updated
to reference the new Attachments example.

* Apply suggestions from code review

* Apply suggestions from code review

* Update apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/index.md

Co-authored-by: Rich Harris <hello@rich-harris.dev>

---------

Co-authored-by: Rich Harris <hello@rich-harris.dev>

Author: kenkunz

apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/index.md

@@ -1,3 +1,5 @@
+import { on } from 'svelte/events';
+
 export function trapFocus(node) {
 	const previous = document.activeElement;
 
@@ -25,8 +27,6 @@ export function trapFocus(node) {
 		}
 	}
 
-	$effect(() => {
-		focusable()[0]?.focus();
-		// TODO finish writing the action
-	});
+	focusable()[0]?.focus();
+	// TODO finish writing the action
 }

apps/svelte.dev/content/tutorial/01-svelte/08-actions/02-adding-parameters-to-actions/index.md

@@ -1,6 +1,6 @@
 <script>
 	import Canvas from './Canvas.svelte';
-	import { trapFocus } from './actions.svelte.js';
+	import { trapFocus } from './attachments.svelte.js';
 
 	const colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet', 'white', 'black'];
 
@@ -27,7 +27,7 @@
 				}
 			}}
 		>
-			<div class="menu" use:trapFocus>
+			<div class="menu" {@attach trapFocus}>
 				<div class="colors">
 					{#each colors as color}
 						<button

apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-a/src/lib/App.svelte renamed to apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-a/src/lib/App.svelte

@@ -1,3 +1,5 @@
+import { on } from 'svelte/events';
+
 export function trapFocus(node) {
 	const previous = document.activeElement;
 
@@ -25,13 +27,11 @@ export function trapFocus(node) {
 		}
 	}
 
-	$effect(() => {
-		focusable()[0]?.focus();
-		node.addEventListener('keydown', handleKeydown);
+	focusable()[0]?.focus();
+	const off = on(node, 'keydown', handleKeydown);
 
-		return () => {
-			node.removeEventListener('keydown', handleKeydown);
-			previous?.focus();
-		};
-	});
+	return () => {
+		off();
+		previous?.focus();
+	};
 }

apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-a/src/lib/Canvas.svelte renamed to apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-a/src/lib/Canvas.svelte

@@ -0,0 +1,62 @@
+---
+title: The attach tag
+---
+
+Attachments are essentially element-level lifecycle functions. They're useful for things like:
+
+- interfacing with third-party libraries
+- lazy-loaded images
+- tooltips
+- adding custom event handlers
+
+In this app, you can scribble on the `<canvas>`, and change colours and brush size via the menu. But if you open the menu and cycle through the options with the Tab key, you'll soon find that the focus isn't _trapped_ inside the modal.
+
+We can fix that with an attachment. Import `trapFocus` from `attachments.svelte.js`...
+
+```svelte
+/// file: App.svelte
+<script>
+	import Canvas from './Canvas.svelte';
+	+++import { trapFocus } from './attachments.svelte.js';+++
+
+	const colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet', 'white', 'black'];
+
+	let selected = $state(colors[0]);
+	let size = $state(10);
+	let showMenu = $state(true);
+</script>
+```
+
+...then add it to the menu with the `{@attach}` tag:
+
+```svelte
+/// file: App.svelte
+<div class="menu" +++{@attach trapFocus}+++>
+```
+
+Let's take a look at the `trapFocus` function in `attachments.svelte.js`. An attachment function is called with a `node` — the `<div class="menu">` in our case — when the node is mounted to the DOM. Attachments run inside an [effect](effects), so they re-run whenever any state read inside the function changes.
+
+First, we need to add an event listener that intercepts Tab key presses:
+
+```js
+/// file: attachments.svelte.js
+focusable()[0]?.focus();
++++const off = on(node, 'keydown', handleKeydown);+++
+```
+
+> [!NOTE] [`on`](/docs/svelte/svelte-events#on) is a wrapper around `addEventListener` that uses <a href="/docs/svelte/basic-markup#Events-Event-delegation">event delegation</a>. It returns a function that removes the handler.
+
+Second, we need to do some cleanup when the node is unmounted — removing the event listener, and restoring focus to where it was before the element mounted. As with effects, an attachment can return a teardown function, which runs immediately before the attachment re-runs or after the element is removed from the DOM:
+
+```js
+/// file: attachments.svelte.js
+focusable()[0]?.focus();
+const off = on(node, 'keydown', handleKeydown);
+
++++return () => {
+	off();
+	previous?.focus();
+};+++
+```
+
+Now, when you open the menu, you can cycle through the options with the Tab key.

apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-a/src/lib/actions.svelte.js renamed to apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-a/src/lib/attachments.svelte.js

@@ -4,17 +4,14 @@
 	let content = $state('Hello!');
 
 	function tooltip(node) {
-		$effect(() => {
-			const tooltip = tippy(node);
-
-			return tooltip.destroy;
-		});
+		const tooltip = tippy(node);
+		return tooltip.destroy;
 	}
 </script>
 
 <input bind:value={content} />
 
-<button use:tooltip>
+<button {@attach tooltip}>
 	Hover me
 </button>