feat: attachments

.changeset/poor-days-pay.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: attachments

packages/svelte/package.json

@@ -33,6 +33,10 @@
       "types": "./types/index.d.ts",
       "default": "./src/animate/index.js"
     },
+    "./attachments": {
+      "types": "./types/index.d.ts",
+      "default": "./src/attachments/index.js"
+    },
     "./compiler": {
       "types": "./types/index.d.ts",
       "require": "./compiler/index.js",

packages/svelte/scripts/generate-types.js

@@ -30,6 +30,7 @@ await createBundle({
 		[pkg.name]: `${dir}/src/index.d.ts`,
 		[`${pkg.name}/action`]: `${dir}/src/action/public.d.ts`,
 		[`${pkg.name}/animate`]: `${dir}/src/animate/public.d.ts`,
+		[`${pkg.name}/attachments`]: `${dir}/src/attachments/index.js`,
 		[`${pkg.name}/compiler`]: `${dir}/src/compiler/public.d.ts`,
 		[`${pkg.name}/easing`]: `${dir}/src/easing/index.js`,
 		[`${pkg.name}/legacy`]: `${dir}/src/legacy/legacy-client.js`,

packages/svelte/src/attachments/index.js

@@ -0,0 +1,4 @@
+export {
+	create_attachment_key as createAttachmentKey,
+	is_attachment_key as isAttachmentKey
+} from '../internal/client/dom/elements/attachments.js';

packages/svelte/src/compiler/phases/1-parse/read/script.js

@@ -16,7 +16,7 @@ const ALLOWED_ATTRIBUTES = ['context', 'generics', 'lang', 'module'];
 /**
  * @param {Parser} parser
  * @param {number} start
- * @param {Array<AST.Attribute | AST.SpreadAttribute | AST.Directive>} attributes
+ * @param {Array<AST.Attribute | AST.SpreadAttribute | AST.Directive | AST.AttachTag>} attributes
  * @returns {AST.Script}
  */
 export function read_script(parser, start, attributes) {

packages/svelte/src/compiler/phases/1-parse/read/style.js

@@ -18,7 +18,7 @@ const REGEX_HTML_COMMENT_CLOSE = /-->/;
 /**
  * @param {Parser} parser
  * @param {number} start
- * @param {Array<AST.Attribute | AST.SpreadAttribute | AST.Directive>} attributes
+ * @param {Array<AST.Attribute | AST.SpreadAttribute | AST.Directive | AST.AttachTag>} attributes
  * @returns {AST.CSS.StyleSheet}
  */
 export default function read_style(parser, start, attributes) {

packages/svelte/src/compiler/phases/1-parse/state/element.js

@@ -480,14 +480,32 @@ function read_static_attribute(parser) {
 
 /**
  * @param {Parser} parser
- * @returns {AST.Attribute | AST.SpreadAttribute | AST.Directive | null}
+ * @returns {AST.Attribute | AST.SpreadAttribute | AST.Directive | AST.AttachTag | null}
  */
 function read_attribute(parser) {
 	const start = parser.index;
 
 	if (parser.eat('{')) {
 		parser.allow_whitespace();
 
+		if (parser.eat('@attach')) {
+			parser.require_whitespace();
+
+			const expression = read_expression(parser);
+			parser.allow_whitespace();
+			parser.eat('}', true);
+
+			/** @type {AST.AttachTag} */
+			const use = {
+				type: 'AttachTag',
+				start,
+				end: parser.index,
+				expression
+			};
+
+			return use;
+		}
+
 		if (parser.eat('...')) {
 			const expression = read_expression(parser);
 

packages/svelte/src/compiler/phases/2-analyze/visitors/shared/component.js

@@ -74,7 +74,8 @@ export function visit_component(node, context) {
 			attribute.type !== 'SpreadAttribute' &&
 			attribute.type !== 'LetDirective' &&
 			attribute.type !== 'OnDirective' &&
-			attribute.type !== 'BindDirective'
+			attribute.type !== 'BindDirective' &&
+			attribute.type !== 'AttachTag'
 		) {
 			e.component_invalid_directive(attribute);
 		}

packages/svelte/src/compiler/phases/3-transform/client/transform-client.js

@@ -56,6 +56,7 @@ import { TitleElement } from './visitors/TitleElement.js';
 import { TransitionDirective } from './visitors/TransitionDirective.js';
 import { UpdateExpression } from './visitors/UpdateExpression.js';
 import { UseDirective } from './visitors/UseDirective.js';
+import { AttachTag } from './visitors/AttachTag.js';
 import { VariableDeclaration } from './visitors/VariableDeclaration.js';
 
 /** @type {Visitors} */
@@ -131,6 +132,7 @@ const visitors = {
 	TransitionDirective,
 	UpdateExpression,
 	UseDirective,
+	AttachTag,
 	VariableDeclaration
 };
 

packages/svelte/src/compiler/phases/3-transform/client/visitors/AttachTag.js

@@ -0,0 +1,21 @@
+/** @import { Expression } from 'estree' */
+/** @import { AST } from '#compiler' */
+/** @import { ComponentContext } from '../types' */
+import * as b from '../../../../utils/builders.js';
+
+/**
+ * @param {AST.AttachTag} node
+ * @param {ComponentContext} context
+ */
+export function AttachTag(node, context) {
+	context.state.init.push(
+		b.stmt(
+			b.call(
+				'$.attach',
+				context.state.node,
+				b.thunk(/** @type {Expression} */ (context.visit(node.expression)))
+			)
+		)
+	);
+	context.next();
+}

packages/svelte/src/compiler/phases/3-transform/client/visitors/RegularElement.js

@@ -82,7 +82,7 @@ export function RegularElement(node, context) {
 	/** @type {AST.StyleDirective[]} */
 	const style_directives = [];
 
-	/** @type {Array<AST.AnimateDirective | AST.BindDirective | AST.OnDirective | AST.TransitionDirective | AST.UseDirective>} */
+	/** @type {Array<AST.AnimateDirective | AST.BindDirective | AST.OnDirective | AST.TransitionDirective | AST.UseDirective | AST.AttachTag>} */
 	const other_directives = [];
 
 	/** @type {ExpressionStatement[]} */
@@ -152,6 +152,10 @@ export function RegularElement(node, context) {
 				has_use = true;
 				other_directives.push(attribute);
 				break;
+
+			case 'AttachTag':
+				other_directives.push(attribute);
+				break;
 		}
 	}
 

packages/svelte/src/compiler/phases/3-transform/client/visitors/shared/component.js

@@ -261,6 +261,16 @@ export function build_component(node, component_name, context, anchor = context.
 					);
 				}
 			}
+		} else if (attribute.type === 'AttachTag') {
+			// TODO do we need to create a derived here?
+			push_prop(
+				b.prop(
+					'get',
+					b.call('$.create_attachment_key'),
+					/** @type {Expression} */ (context.visit(attribute.expression)),
+					true
+				)
+			);
 		}
 	}
 

packages/svelte/src/compiler/types/template.d.ts

@@ -174,6 +174,12 @@ export namespace AST {
 		};
 	}
 
+	/** A `{@attach foo(...)} tag */
+	export interface AttachTag extends BaseNode {
+		type: 'AttachTag';
+		expression: Expression;
+	}
+
 	/** An `animate:` directive */
 	export interface AnimateDirective extends BaseNode {
 		type: 'AnimateDirective';
@@ -273,7 +279,7 @@ export namespace AST {
 
 	interface BaseElement extends BaseNode {
 		name: string;
-		attributes: Array<Attribute | SpreadAttribute | Directive>;
+		attributes: Array<Attribute | SpreadAttribute | Directive | AttachTag>;
 		fragment: Fragment;
 	}
 
@@ -549,6 +555,7 @@ export namespace AST {
 		| AST.Attribute
 		| AST.SpreadAttribute
 		| Directive
+		| AST.AttachTag
 		| AST.Comment
 		| Block;
 

packages/svelte/src/internal/client/dom/elements/attachments.js

@@ -0,0 +1,30 @@
+import { effect } from '../../reactivity/effects.js';
+
+const key = `@attach-${/*@__PURE__*/ Math.random().toString(36).slice(2)}`;
+const name = `Symbol(${key})`;
+
+// TODO this feels a bit belt-and-braces to me, tbh — are we sure we need it?
+/**
+ * Creates a `Symbol` that Svelte recognises as an attachment key
+ */
+export function create_attachment_key() {
+	return Symbol(key);
+}
+
+/**
+ * Returns `true` if the symbol was created with `createAttachmentKey`
+ * @param {string | symbol} key
+ */
+export function is_attachment_key(key) {
+	return typeof key === 'symbol' && key.toString() === name;
+}
+
+/**
+ * @param {Element} node
+ * @param {() => (node: Element) => void} get_fn
+ */
+export function attach(node, get_fn) {
+	effect(() => {
+		return get_fn()(node);
+	});
+}

packages/svelte/src/internal/client/dom/elements/attributes.js

@@ -13,6 +13,7 @@ import {
 	set_active_effect,
 	set_active_reaction
 } from '../../runtime.js';
+import { attach, is_attachment_key } from './attachments.js';
 import { clsx } from '../../../shared/attributes.js';
 
 /**
@@ -245,8 +246,8 @@ export function set_custom_element_data(node, prop, value) {
 /**
  * Spreads attributes onto a DOM element, taking into account the currently set attributes
  * @param {Element & ElementCSSInlineStyle} element
- * @param {Record<string, any> | undefined} prev
- * @param {Record<string, any>} next New attributes - this function mutates this object
+ * @param {Record<string | symbol, any> | undefined} prev
+ * @param {Record<string | symbol, any>} next New attributes - this function mutates this object
  * @param {string} [css_hash]
  * @param {boolean} [preserve_attribute_case]
  * @param {boolean} [is_custom_element]
@@ -415,6 +416,12 @@ export function set_attributes(
 		}
 	}
 
+	for (let symbol of Object.getOwnPropertySymbols(next)) {
+		if (is_attachment_key(symbol)) {
+			attach(element, () => next[symbol]);
+		}
+	}
+
 	return current;
 }
 

packages/svelte/src/internal/client/index.js

@@ -27,6 +27,7 @@ export { element } from './dom/blocks/svelte-element.js';
 export { head } from './dom/blocks/svelte-head.js';
 export { append_styles } from './dom/css.js';
 export { action } from './dom/elements/actions.js';
+export { attach, create_attachment_key, is_attachment_key } from './dom/elements/attachments.js';
 export {
 	remove_input_defaults,
 	set_attribute,

packages/svelte/tests/parser-modern/samples/attachments/input.svelte

@@ -0,0 +1 @@
+<div {@attach (node) => {}} {@attach (node) => {}}></div>