Should svelte/events on add support for window and document?

[leon]

I was trying to add a simple keyboard command

and usually you bind keyboard events against either the window or the document.

to be able to handle cleanup easier I wanted to use svelte/events on function.

but the generic parameter says the first param should be a decendant of HTMLElement, which window and document don't seem to be which causes the second param to not be of type KeyboardEvent.

I was able to get around it by forcing it to be a HTMLElement, but that seems bad

import { on } from 'svelte/events'

$effect(() =>
    on(window as unknown as HTMLElement, 'keydown', (event: KeyboardEvent) => {
      if (event.key === 'd' && event.ctrlKey) {
        showDebugMenu = !showDebugMenu
      }
    }),
  )

Are we not supposed to use on for window and document?
or is it that the typescript types needs updating to include window and document?

[kwangure]

on will accept any EventTarget. window is an EventTarget so it's perfectly valid.

It works fine. Test it the Svelte REPL here.

You can also inspect implementation in your node_modules. See src/internal/client/dom/elements/events.js:

/**
 * @param {EventTarget} element
 * @param {string} type
 * @param {EventListener} handler
 * @param {AddEventListenerOptions} [options]
 */
export function on(element, type, handler, options = {}) {
	var target_handler = create_event(type, element, handler, options);

	return () => {
		element.removeEventListener(type, target_handler, options);
	};
}

I'm not sure when you say "force to a HTMLElement", you're referring to changing the type or you think you changed the value. Just in case it's a misunderstanding with how TypeScript works, I'll mention that TypeScript does not "force" the window to be a HTMLElement. TypeScript checks types statically, but all those types are stripped away when compiled and do not affect the runtime code at all. See this quick read for a more detailed explanation.

I'm also not sure why you're creating listeners in an effect. It could be what you actually want to do to for some reason, but I somehow very thoroughly doubt it?

[leon]

Yes, but the typescript typings don't work.

I need to either explicitly or implicitly get the KeyboardEvent so that I can get key and other fields.

This fails

on(window, 'keydown', (event: KeyboardEvent) => {
      if (event.key === 'd' && event.ctrlKey) {
        count++
      }
    })

The best outcome would be if typescript could automatically figure out what type of event keydown is.

on(window, 'keydown', (event) => {
      if (event.key === 'd' && event.ctrlKey) {
        count++
      }
    })

[kwangure]

Ah. I see your frustration. Here are the types defined in Svelte (right click, and select "Go To Type Definition" if using VS Code).

declare module 'svelte/events' {
	/**
	 * 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: EventTarget, type: string, handler: EventListener, options?: AddEventListenerOptions | undefined): () => void;

	export {};
}

Note the two definitions for HTMLElement and EventTarget. The event handler will automatically "just work" for HTMLElement event handlers because the HTMLElementEventMap links 'keydown' to KeyboardEvent. For other, EventTargets that are not elements, it's typed as a general Event, which is a reasonable assumption and the best guess you can make.

window.dispatchEvent(new CustomEvent('keydown'));

You have three options:

on(window, 'keydown', (event: Event) => {
	// 1. Hey TypeScript, trust me I know more than you, pretend this is a `KeyboardEvent`
	const _event = event as KeyboardEvent;
	if (_event.key === 'd' && _event.ctrlKey) {}

	// 2. Hey TypeScript, let's confirm together that `event` is not only an `Event` but also a `KeyboardEvent`
	if (event instanceof KeyboardEvent) {
		if (event.key === 'd' && event.ctrlKey) {
			// do something
		}
	}
});

// 3. Use a HTMLElement. i.e. The root <html/> element.
on(document.documentElement, 'keydown', (event /* A `KeyboardEvent`. Yay!🎉*/) => { ... })

[leon]

Binding events to window or document is a very common thing.
could we not add an overload to the typings so that we get automatic type inference in the same way as for the HTMLElement?

The ways you describe are to me workarounds, not something that we should promote.

[leon]

If we add these two declarations we can get the correct typings for both window and document

/**
	 * 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 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: Document, event: WindowEventMap[Type]) => any, options?: AddEventListenerOptions | undefined): () => void;

[kwangure]

Seems reasonable. Open an issue for it. A PR to match wouldn't hurt either.