fix: add document and window to svelte/events on types. (#13260)

fixes #13259
fixes #12665 

put it into dts for now because of https://github.com/microsoft/TypeScript/issues/59980

---------

Co-authored-by: Simon Holthausen <simon.holthausen@vercel.com>

packages/svelte/scripts/generate-types.js

@@ -37,7 +37,7 @@ await createBundle({
 		[`${pkg.name}/server`]: `${dir}/src/server/index.d.ts`,
 		[`${pkg.name}/store`]: `${dir}/src/store/public.d.ts`,
 		[`${pkg.name}/transition`]: `${dir}/src/transition/public.d.ts`,
-		[`${pkg.name}/events`]: `${dir}/src/events/index.js`,
+		[`${pkg.name}/events`]: `${dir}/src/events/public.d.ts`,
 		// TODO remove in Svelte 6
 		[`${pkg.name}/types/compiler/preprocess`]: `${dir}/src/compiler/preprocess/legacy-public.d.ts`,
 		[`${pkg.name}/types/compiler/interfaces`]: `${dir}/src/compiler/types/legacy-interfaces.d.ts`

packages/svelte/src/events/public.d.ts

@@ -0,0 +1,57 @@
+// Once https://github.com/microsoft/TypeScript/issues/59980 is fixed we can put these overloads into the JSDoc comments of the `on` function
+
+/**
+ * Attaches an event handler to the window and returns a function that removes the handler. Using this
+ * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
+ * (with attributes like `onclick`), which use event delegation for performance reasons
+ */
+export function on<Type extends keyof WindowEventMap>(
+	window: Window,
+	type: Type,
+	handler: (this: Window, event: WindowEventMap[Type]) => any,
+	options?: AddEventListenerOptions | undefined
+): () => void;
+/**
+ * Attaches an event handler to the document and returns a function that removes the handler. Using this
+ * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
+ * (with attributes like `onclick`), which use event delegation for performance reasons
+ */
+export function on<Type extends keyof DocumentEventMap>(
+	document: Document,
+	type: Type,
+	handler: (this: Document, event: DocumentEventMap[Type]) => any,
+	options?: AddEventListenerOptions | undefined
+): () => void;
+/**
+ * Attaches an event handler to an element and returns a function that removes the handler. Using this
+ * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
+ * (with attributes like `onclick`), which use event delegation for performance reasons
+ */
+export function on<Element extends HTMLElement, Type extends keyof HTMLElementEventMap>(
+	element: Element,
+	type: Type,
+	handler: (this: Element, event: HTMLElementEventMap[Type]) => any,
+	options?: AddEventListenerOptions | undefined
+): () => void;
+/**
+ * Attaches an event handler to an element and returns a function that removes the handler. Using this
+ * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
+ * (with attributes like `onclick`), which use event delegation for performance reasons
+ */
+export function on<Element extends MediaQueryList, Type extends keyof MediaQueryListEventMap>(
+	element: Element,
+	type: Type,
+	handler: (this: Element, event: MediaQueryListEventMap[Type]) => any,
+	options?: AddEventListenerOptions | undefined
+): () => void;
+/**
+ * Attaches an event handler to an element and returns a function that removes the handler. Using this
+ * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
+ * (with attributes like `onclick`), which use event delegation for performance reasons
+ */
+export function on(
+	element: EventTarget,
+	type: string,
+	handler: EventListener,
+	options?: AddEventListenerOptions | undefined
+): () => void;

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

@@ -83,30 +83,6 @@ export function create_event(event_name, dom, handler, options) {
  * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
  * (with attributes like `onclick`), which use event delegation for performance reasons
  *
- * @template {HTMLElement} Element
- * @template {keyof HTMLElementEventMap} Type
- * @overload
- * @param {Element} element
- * @param {Type} type
- * @param {(this: Element, event: HTMLElementEventMap[Type]) => any} handler
- * @param {AddEventListenerOptions} [options]
- * @returns {() => void}
- */
-
-/**
- * Attaches an event handler to an element and returns a function that removes the handler. Using this
- * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
- * (with attributes like `onclick`), which use event delegation for performance reasons
- *
- * @overload
- * @param {EventTarget} element
- * @param {string} type
- * @param {EventListener} handler
- * @param {AddEventListenerOptions} [options]
- * @returns {() => void}
- */
-
-/**
  * @param {EventTarget} element
  * @param {string} type
  * @param {EventListener} handler

packages/svelte/tests/types/events.ts

@@ -4,6 +4,10 @@ import { on } from 'svelte/events';
 
 on(document.body, 'click', (e) => e.button);
 
+on(window, 'click', (e) => e.button);
+
+on(document, 'click', (e) => e.button);
+
 on(
 	document.body,
 	'clidck',
@@ -12,14 +16,6 @@ on(
 		e.button
 );
 
-on(
-	window,
-	'click',
-	(e) =>
-		// @ts-expect-error ideally we'd know this is a MouseEvent here, too, but for keeping the types sane, we currently don't
-		e.button
-);
-
 on(
 	// @ts-expect-error
 	'asd',

packages/svelte/tsconfig.json

@@ -19,7 +19,7 @@
 			"svelte": ["./src/index.d.ts"],
 			"svelte/action": ["./src/action/public.d.ts"],
 			"svelte/compiler": ["./src/compiler/public.d.ts"],
-			"svelte/events": ["./src/events/index.js"],
+			"svelte/events": ["./src/events/public.d.ts"],
 			"svelte/internal/client": ["./src/internal/client/index.js"],
 			"svelte/legacy": ["./src/legacy/legacy-client.js"],
 			"svelte/motion": ["./src/motion/public.d.ts"],

packages/svelte/types/index.d.ts

@@ -1991,20 +1991,63 @@ declare module 'svelte/transition' {
 }
 
 declare module 'svelte/events' {
+	// Once https://github.com/microsoft/TypeScript/issues/59980 is fixed we can put these overloads into the JSDoc comments of the `on` function
+
+	/**
+	 * Attaches an event handler to the window and returns a function that removes the handler. Using this
+	 * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
+	 * (with attributes like `onclick`), which use event delegation for performance reasons
+	 */
+	export function on<Type extends keyof WindowEventMap>(
+		window: Window,
+		type: Type,
+		handler: (this: Window, event: WindowEventMap[Type]) => any,
+		options?: AddEventListenerOptions | undefined
+	): () => void;
+	/**
+	 * Attaches an event handler to the document and returns a function that removes the handler. Using this
+	 * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
+	 * (with attributes like `onclick`), which use event delegation for performance reasons
+	 */
+	export function on<Type extends keyof DocumentEventMap>(
+		document: Document,
+		type: Type,
+		handler: (this: Document, event: DocumentEventMap[Type]) => any,
+		options?: AddEventListenerOptions | undefined
+	): () => void;
 	/**
 	 * Attaches an event handler to an element and returns a function that removes the handler. Using this
 	 * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
 	 * (with attributes like `onclick`), which use event delegation for performance reasons
-	 *
-	 * */
-	export function on<Element extends HTMLElement, Type extends keyof HTMLElementEventMap>(element: Element, type: Type, handler: (this: Element, event: HTMLElementEventMap[Type]) => any, options?: AddEventListenerOptions | undefined): () => void;
+	 */
+	export function on<Element extends HTMLElement, Type extends keyof HTMLElementEventMap>(
+		element: Element,
+		type: Type,
+		handler: (this: Element, event: HTMLElementEventMap[Type]) => any,
+		options?: AddEventListenerOptions | undefined
+	): () => void;
 	/**
 	 * Attaches an event handler to an element and returns a function that removes the handler. Using this
 	 * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
 	 * (with attributes like `onclick`), which use event delegation for performance reasons
-	 *
-	 * */
-	export function on(element: EventTarget, type: string, handler: EventListener, options?: AddEventListenerOptions | undefined): () => void;
+	 */
+	export function on<Element extends MediaQueryList, Type extends keyof MediaQueryListEventMap>(
+		element: Element,
+		type: Type,
+		handler: (this: Element, event: MediaQueryListEventMap[Type]) => any,
+		options?: AddEventListenerOptions | undefined
+	): () => void;
+	/**
+	 * Attaches an event handler to an element and returns a function that removes the handler. Using this
+	 * rather than `addEventListener` will preserve the correct order relative to handlers added declaratively
+	 * (with attributes like `onclick`), which use event delegation for performance reasons
+	 */
+	export function on(
+		element: EventTarget,
+		type: string,
+		handler: EventListener,
+		options?: AddEventListenerOptions | undefined
+	): () => void;
 
 	export {};
 }