feat: $props.id(), a SSR-safe ID generation (#15185)

* first impl of $$uid

* fix

* $props.id()

* fix errors

* rename $.create_uid() into $.props_id()

* fix message

* relax const requirement, validate assignments instead

* oops

* simplify

* non-constants should be lowercased

* ditto

* start at 1

* add docs

* changeset

* add test

* add docs

* doc : add code example

* fix type reported by bennymi

---------

Co-authored-by: Rich Harris <[email protected]>

Author: adiguba

.changeset/hip-singers-vanish.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: SSR-safe ID generation with `$props.id()`

documentation/docs/02-runes/05-$props.md

@@ -199,3 +199,24 @@ You can, of course, separate the type declaration from the annotation:
 > [!NOTE] Interfaces for native DOM elements are provided in the `svelte/elements` module (see [Typing wrapper components](typescript#Typing-wrapper-components))
 
 Adding types is recommended, as it ensures that people using your component can easily discover which props they should provide.
+
+
+## `$props.id()`
+
+This rune, added in version 5.20.0, generates an ID that is unique to the current component instance. When hydrating a server-rendered component, the value will be consistent between server and client.
+
+This is useful for linking elements via attributes like `for` and `aria-labelledby`.
+
+```svelte
+<script>
+	const uid = $props.id();
+</script>
+
+<form>
+	<label for="{uid}-firstname">First Name: </label>
+	<input id="{uid}-firstname" type="text" />
+
+	<label for="{uid}-lastname">Last Name: </label>
+	<input id="{uid}-lastname" type="text" />
+</form>
+```

documentation/docs/98-reference/.generated/compile-errors.md

@@ -573,7 +573,13 @@ Unrecognised compiler option %keypath%
 ### props_duplicate
 
 ```
-Cannot use `$props()` more than once
+Cannot use `%rune%()` more than once
+```
+
+### props_id_invalid_placement
+
+```
+`$props.id()` can only be used at the top level of components as a variable declaration initializer
 ```
 
 ### props_illegal_name

packages/svelte/messages/compile-errors/script.md

@@ -120,7 +120,11 @@ This turned out to be buggy and unpredictable, particularly when working with de
 
 ## props_duplicate
 
-> Cannot use `$props()` more than once
+> Cannot use `%rune%()` more than once
+
+## props_id_invalid_placement
+
+> `$props.id()` can only be used at the top level of components as a variable declaration initializer
 
 ## props_illegal_name
 

packages/svelte/src/ambient.d.ts

@@ -339,6 +339,15 @@ declare namespace $effect {
 declare function $props(): any;
 
 declare namespace $props {
+	/**
+	 * Generates an ID that is unique to the current component instance. When hydrating a server-rendered component,
+	 * the value will be consistent between server and client.
+	 *
+	 * This is useful for linking elements via attributes like `for` and `aria-labelledby`.
+	 * @since 5.20.0
+	 */
+	export function id(): string;
+
 	// prevent intellisense from being unhelpful
 	/** @deprecated */
 	export const apply: never;

packages/svelte/src/compiler/errors.js

@@ -279,12 +279,22 @@ export function module_illegal_default_export(node) {
 }
 
 /**
- * Cannot use `$props()` more than once
+ * Cannot use `%rune%()` more than once
+ * @param {null | number | NodeLike} node
+ * @param {string} rune
+ * @returns {never}
+ */
+export function props_duplicate(node, rune) {
+	e(node, 'props_duplicate', `Cannot use \`${rune}()\` more than once\nhttps://svelte.dev/e/props_duplicate`);
+}
+
+/**
+ * `$props.id()` can only be used at the top level of components as a variable declaration initializer
  * @param {null | number | NodeLike} node
  * @returns {never}
  */
-export function props_duplicate(node) {
-	e(node, 'props_duplicate', `Cannot use \`$props()\` more than once\nhttps://svelte.dev/e/props_duplicate`);
+export function props_id_invalid_placement(node) {
+	e(node, 'props_id_invalid_placement', `\`$props.id()\` can only be used at the top level of components as a variable declaration initializer\nhttps://svelte.dev/e/props_id_invalid_placement`);
 }
 
 /**

packages/svelte/src/compiler/phases/2-analyze/index.js

@@ -416,6 +416,7 @@ export function analyze_component(root, source, options) {
 		immutable: runes || options.immutable,
 		exports: [],
 		uses_props: false,
+		props_id: null,
 		uses_rest_props: false,
 		uses_slots: false,
 		uses_component_bindings: false,

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

@@ -55,7 +55,7 @@ export function CallExpression(node, context) {
 
 		case '$props':
 			if (context.state.has_props_rune) {
-				e.props_duplicate(node);
+				e.props_duplicate(node, rune);
 			}
 
 			context.state.has_props_rune = true;
@@ -74,6 +74,32 @@ export function CallExpression(node, context) {
 
 			break;
 
+		case '$props.id': {
+			const grand_parent = get_parent(context.path, -2);
+
+			if (context.state.analysis.props_id) {
+				e.props_duplicate(node, rune);
+			}
+
+			if (
+				parent.type !== 'VariableDeclarator' ||
+				parent.id.type !== 'Identifier' ||
+				context.state.ast_type !== 'instance' ||
+				context.state.scope !== context.state.analysis.instance.scope ||
+				grand_parent.type !== 'VariableDeclaration'
+			) {
+				e.props_id_invalid_placement(node);
+			}
+
+			if (node.arguments.length > 0) {
+				e.rune_invalid_arguments(node, rune);
+			}
+
+			context.state.analysis.props_id = parent.id;
+
+			break;
+		}
+
 		case '$state':
 		case '$state.raw':
 		case '$derived':

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

@@ -25,6 +25,10 @@ export function validate_assignment(node, argument, state) {
 				e.constant_assignment(node, 'derived state');
 			}
 
+			if (binding?.node === state.analysis.props_id) {
+				e.constant_assignment(node, '$props.id()');
+			}
+
 			if (binding?.kind === 'each') {
 				e.each_item_invalid_assignment(node);
 			}

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

@@ -562,6 +562,11 @@ export function client_component(analysis, options) {
 		component_block.body.unshift(b.stmt(b.call('$.check_target', b.id('new.target'))));
 	}
 
+	if (analysis.props_id) {
+		// need to be placed on first line of the component for hydration
+		component_block.body.unshift(b.const(analysis.props_id, b.call('$.props_id')));
+	}
+
 	if (state.events.size > 0) {
 		body.push(
 			b.stmt(b.call('$.delegate', b.array(Array.from(state.events).map((name) => b.literal(name)))))