docs: attachment tutorial

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

@@ -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/01-actions/+assets/app-b/src/lib/App.svelte → apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-b/src/lib/App.svelte

@@ -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-b/src/lib/actions.svelte.js → apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-b/src/lib/attachments.svelte.js

@@ -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-attachments/01-attach/index.md

@@ -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/02-adding-parameters-to-actions/+assets/app-a/src/lib/App.svelte → apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/+assets/app-a/src/lib/App.svelte

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

apps/svelte.dev/content/tutorial/01-svelte/08-actions/02-adding-parameters-to-actions/+assets/app-b/src/lib/App.svelte → apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/+assets/app-b/src/lib/App.svelte

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

apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/index.md

@@ -0,0 +1,42 @@
+---
+title: Attachment factories
+---
+
+Often, you need an attachment to depend on some parameters or component state. In this scenario, you can use an [attachment factory](/docs/svelte/@attach#Attachment-factories) — a function that _returns_ an attachment.
+
+In this exercise, we want to add a tooltip to the `<button>` using the [`Tippy.js`](https://atomiks.github.io/tippyjs/) library. The attachment is already wired up with `{@attach tooltip}`, but if you hover over the button (or focus it with the keyboard) the tooltip contains no content.
+
+First, we need to convert our simple attachment into a _factory_ function that returns an attachment.
+
+```js
+/// file: App.svelte
+function tooltip(---node---) {
++++	return (node) => {+++
+		const tooltip = tippy(node);
+		return tooltip.destroy;
++++	};+++
+}
+```
+
+Next, the factory needs to accept the options we want to pass to Tippy (in this case just `content`):
+
+```js
+/// file: App.svelte
+function tooltip(+++content+++) {
+	return (node) => {
+		const tooltip = tippy(node+++, { content }+++);
+		return tooltip.destroy;
+	};
+}
+```
+
+> [!NOTE] The `tooltip(content)` expression runs inside an effect, so the attachment is destroyed and recreated whenever content changes.
+
+Finally, we need to call the attachment factory and pass the `content` argument in our `{@attach}` tag:
+
+```svelte
+/// file: App.svelte
+<button {@attach tooltip+++(content)+++}>
+	Hover me
+</button>
+```

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

@@ -1,5 +1,5 @@
 ---
-title: Actions
+title: Attachments
 scope: { 'prefix': '/src/lib/', 'name': 'src' }
 focus: /src/lib/App.svelte
 ---

apps/svelte.dev/content/tutorial/02-advanced-svelte/04-advanced-bindings/07-component-this/+assets/app-a/src/lib/App.svelte

@@ -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/02-advanced-svelte/04-advanced-bindings/07-component-this/+assets/app-a/src/lib/actions.svelte.js → apps/svelte.dev/content/tutorial/02-advanced-svelte/04-advanced-bindings/07-component-this/+assets/app-a/src/lib/attachments.svelte.js

@@ -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/02-advanced-svelte/04-advanced-bindings/07-component-this/+assets/app-b/src/lib/App.svelte

@@ -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'];
 
@@ -29,7 +29,7 @@
 				}
 			}}
 		>
-			<div class="menu" use:trapFocus>
+			<div class="menu" {@attach trapFocus}>
 				<div class="colors">
 					{#each colors as color}
 						<button

apps/svelte.dev/content/tutorial/02-advanced-svelte/04-advanced-bindings/07-component-this/index.md

@@ -4,7 +4,7 @@ title: Binding to component instances
 
 Just as you can bind to DOM elements, you can bind to component instances themselves with `bind:this`.
 
-This is useful in the rare cases that you need to interact with a component programmatically (rather than by providing it with updated props). Revisiting our canvas app from [a few exercises ago](actions), it would be nice to add a button to clear the screen.
+This is useful in the rare cases that you need to interact with a component programmatically (rather than by providing it with updated props). Revisiting our canvas app from [a few exercises ago](attach), it would be nice to add a button to clear the screen.
 
 First, let's export a function from `Canvas.svelte`: