fix: use typedef for JSDoc props and maintain comments (#13698)

* fix: use typedef for JSDoc props and maintain comments

* chore: add comments

* chore: add extra spaces and delete commented line

Author: paoloricciuti

.changeset/sweet-melons-itch.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+fix: use typedef for JSDoc props and maintain comments

packages/svelte/src/compiler/migrate/index.js

@@ -213,23 +213,18 @@ export function migrate(source, { filename } = {}) {
 					}
 					type += `\n${indent}}`;
 				} else {
-					type = `{${state.props
+					type = `/**\n${indent} * @typedef {Object} ${type_name}${state.props
 						.map((prop) => {
-							return `${prop.exported}${prop.optional ? '?' : ''}: ${prop.type}`;
+							return `\n${indent} * @property {${prop.type}} ${prop.optional ? `[${prop.exported}]` : prop.exported}${prop.comment ? ` - ${prop.comment}` : ''}`;
 						})
-						.join(`, `)}`;
-					if (analysis.uses_props || analysis.uses_rest_props) {
-						type += `${state.props.length > 0 ? ', ' : ''}[key: string]: any`;
-					}
-					type += '}';
+						.join(``)}\n${indent} */`;
 				}
-
 				let props_declaration = `let {${props_separator}${props}${has_many_props ? `\n${indent}` : ' '}}`;
 				if (uses_ts) {
 					props_declaration = `${type}\n\n${indent}${props_declaration}`;
 					props_declaration = `${props_declaration}${type ? `: ${type_name}` : ''} = $props();`;
 				} else {
-					props_declaration = `/** @type {${type}} */\n${indent}${props_declaration}`;
+					props_declaration = `${type && state.props.length > 0 ? `${type}\n\n${indent}` : ''}/** @type {${state.props.length > 0 ? type_name : ''}${analysis.uses_props || analysis.uses_rest_props ? `${state.props.length > 0 ? ' & ' : ''}{ [key: string]: any }` : ''}} */\n${indent}${props_declaration}`;
 					props_declaration = `${props_declaration} = $props();`;
 				}
 
@@ -1265,11 +1260,10 @@ function extract_type_and_comment(declarator, str, path) {
 
 	// Try to find jsdoc above the declaration
 	let comment_node = /** @type {Node} */ (parent)?.leadingComments?.at(-1);
-	if (comment_node?.type !== 'Block') comment_node = undefined;
 
 	const comment_start = /** @type {any} */ (comment_node)?.start;
 	const comment_end = /** @type {any} */ (comment_node)?.end;
-	const comment = comment_node && str.original.substring(comment_start, comment_end);
+	let comment = comment_node && str.original.substring(comment_start, comment_end);
 
 	if (comment_node) {
 		str.update(comment_start, comment_end, '');
@@ -1283,11 +1277,31 @@ function extract_type_and_comment(declarator, str, path) {
 		return { type: str.original.substring(start, declarator.id.typeAnnotation.end), comment };
 	}
 
+	let cleaned_comment = comment
+		?.split('\n')
+		.map((line) =>
+			line
+				.trim()
+				// replace `// ` for one liners
+				.replace(/^\/\/\s*/g, '')
+				// replace `\**` for the initial JSDoc
+				.replace(/^\/\*\*?\s*/g, '')
+				// migrate `*/` for the end of JSDoc
+				.replace(/\s*\*\/$/g, '')
+				// remove any initial `* ` to clean the comment
+				.replace(/^\*\s*/g, '')
+		)
+		.filter(Boolean);
+	const first_at_comment = cleaned_comment?.findIndex((line) => line.startsWith('@'));
+	comment = cleaned_comment
+		?.slice(0, first_at_comment !== -1 ? first_at_comment : cleaned_comment.length)
+		.join('\n');
+
 	// try to find a comment with a type annotation, hinting at jsdoc
 	if (parent?.type === 'ExportNamedDeclaration' && comment_node) {
 		const match = /@type {(.+)}/.exec(comment_node.value);
 		if (match) {
-			return { type: match[1] };
+			return { type: match[1], comment };
 		}
 	}
 

packages/svelte/tests/migrate/samples/$$slots-used-as-variable-$$props/output.svelte

@@ -1,5 +1,11 @@
 <script>
-	/** @type {{message?: import('svelte').Snippet, extra?: import('svelte').Snippet<[any]>, [key: string]: any}} */
+	/**
+	 * @typedef {Object} Props
+	 * @property {import('svelte').Snippet} [message]
+	 * @property {import('svelte').Snippet<[any]>} [extra]
+	 */
+
+	/** @type {Props & { [key: string]: any }} */
 	let { ...props } = $props();
 	let showMessage = props.message;
 	let extraTitle = $derived(props.extra);

packages/svelte/tests/migrate/samples/$$slots-used-as-variable/output.svelte

@@ -1,5 +1,13 @@
 <script>
-	/** @type {{message?: import('svelte').Snippet, showMessage?: any, title?: import('svelte').Snippet<[any]>, extra?: import('svelte').Snippet<[any]>}} */
+	/**
+	 * @typedef {Object} Props
+	 * @property {import('svelte').Snippet} [message]
+	 * @property {any} [showMessage]
+	 * @property {import('svelte').Snippet<[any]>} [title]
+	 * @property {import('svelte').Snippet<[any]>} [extra]
+	 */
+
+	/** @type {Props} */
 	let {
 		message,
 		showMessage = message,

packages/svelte/tests/migrate/samples/css-ignore/output.svelte

@@ -1,5 +1,10 @@
 <script>
-	/** @type {{name: any}} */
+	/**
+	 * @typedef {Object} Props
+	 * @property {any} name
+	 */
+
+	/** @type {Props} */
 	let { name } = $props();
 </script>
 

packages/svelte/tests/migrate/samples/jsdoc-with-comments/input.svelte

@@ -0,0 +1,28 @@
+<script>
+	/**
+	 * My wonderful comment
+	 * @type {string}
+	 */
+	export let comment;
+
+	/**
+	 * My wonderful other comment
+	 * @type {number}
+	 */	
+	export let another_comment;
+
+	// one line comment
+	export let one_line;
+
+	export let no_comment;
+
+	/**
+	 * @type {boolean}
+	 */
+	export let type_no_comment;
+
+	/**
+	 * This is optional
+	 */
+	 export let optional = {stuff: true};
+</script>

packages/svelte/tests/migrate/samples/jsdoc-with-comments/output.svelte

@@ -0,0 +1,31 @@
+<script>
+	
+
+		
+
+	
+
+
+	
+
+	
+	/**
+	 * @typedef {Object} Props
+	 * @property {string} comment - My wonderful comment
+	 * @property {number} another_comment - My wonderful other comment
+	 * @property {any} one_line - one line comment
+	 * @property {any} no_comment
+	 * @property {boolean} type_no_comment
+	 * @property {any} [optional] - This is optional
+	 */
+
+	/** @type {Props} */
+	let {
+		comment,
+		another_comment,
+		one_line,
+		no_comment,
+		type_no_comment,
+		optional = {stuff: true}
+	} = $props();
+</script>

packages/svelte/tests/migrate/samples/props-and-labeled/output.svelte

@@ -1,5 +1,11 @@
 <script>
-	/** @type {{readonly: any, optional?: string}} */
+	/**
+	 * @typedef {Object} Props
+	 * @property {any} readonly
+	 * @property {string} [optional]
+	 */
+
+	/** @type {Props} */
 	let { readonly, optional = 'foo' } = $props();
 	let writable = $derived(!readonly);
 </script>

packages/svelte/tests/migrate/samples/props-rest-props/output.svelte

@@ -1,5 +1,10 @@
 <script>
-    /** @type {{foo: any, [key: string]: any}} */
+    /**
+     * @typedef {Object} Props
+     * @property {any} foo
+     */
+
+    /** @type {Props & { [key: string]: any }} */
     let { foo, ...rest } = $props();
 </script>
 

packages/svelte/tests/migrate/samples/props/output.svelte

@@ -1,6 +1,14 @@
 <script>
 	
-	/** @type {{readonly: Record<string, { href: string; title: string; }[]>, optional?: string, binding: any, bindingOptional?: string}} */
+	/**
+	 * @typedef {Object} Props
+	 * @property {Record<string, { href: string; title: string; }[]>} readonly
+	 * @property {string} [optional]
+	 * @property {any} binding
+	 * @property {string} [bindingOptional]
+	 */
+
+	/** @type {Props} */
 	let {
 		readonly,
 		optional = 'foo',