Repository: TypeScript
Issue: Associate HTML Elements and EventMaps in a map
Labels: Suggestion,Awaiting More Feedback

<!-- 🚨 STOP 🚨 𝗦𝗧𝗢𝗣 🚨 𝑺𝑻𝑶𝑷 🚨

Half of all issues filed here are duplicates, answered in the FAQ, or not appropriate for the bug tracker.

Please help us by doing the following steps before logging an issue:
  * Search: https://github.com/Microsoft/TypeScript/search?type=Issues
  * Read the FAQ, especially the "Common Feature Requests" section: https://github.com/Microsoft/TypeScript/wiki/FAQ

-->

## Search Terms

- dom.d.ts
- eventmap

<!-- List of keywords you searched for before creating this issue. Write them down here so that others can find this suggestion more easily -->

## Suggestion

Create a "map" that pairs `HTMLElement` with it's relevant `EventMap` types.

We can infer a `tagName` from a `HTMLElement`  and visa-versa, from the `HTMLElementTagNameMap` type.

```ts

type GetHTMLElementByTagName<
  K extends keyof HTMLElementTagNameMap
> = HTMLElementTagNameMap[K];

type GetTagNameByHTMLElement<
  E extends HTMLElementTagNameMap[keyof HTMLElementTagNameMap]
> = {
  [P in keyof HTMLElementTagNameMap]: HTMLElementTagNameMap[P] extends E
    ? P
    : never;
}[keyof HTMLElementTagNameMap];


```

But there is currently no way with Typescript's type system to infer what the event map of an element is from the existing types in `dom.d.ts`.



```ts
interface HTMLElement  extends ... {

// ...
// how to extract type HTMLElementEventMap from keyof HTMLElementEventMap?
  addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
// ...
```

<!-- A summary of what you'd like to see added or changed -->

## Use Cases

It would be nice to create our own versions of `[element].(add|remove)EventListener()`. For the drag and drop library `sortablejs`, we expose a helper that is  `[element].(add|remove)EventListener()` that assigns the capture value based on the browser.

```ts
function off(el, event, fn) {
  el.removeEventListener(event, fn, captureMode());
}
```

Unfortunately, I cannot infer the `event` and `fn` function parameters from the element `el` with generics.


<!--
What do you want to use this for?
What shortcomings exist with current approaches?
-->

## Examples

All these other "map" implementations are `string <-> Type` pairs using an interface, where as we'll need `Type <-> Type` pairs.

<!-- Show how this would be used and what the behavior would be -->

```ts
// dom.d.ts
interface HTMLElementTagNameMap {
    "a": HTMLAnchorElement;
    "abbr": HTMLElement;
    "address": HTMLElement;
    "applet": HTMLAppletElement;
    // ...
}
```

Here is the janky work around I've come  up with so far. [You can see more in `dom-ts`](https://github.com/waynevanson/dom-ts). I figured many other users would want this, which is why I've created this issue.

```ts
// helper
export type CreateElementMeta<R extends string, E extends Element, A extends ElementEventMap> = {
  _tagName: R
  _element: E
  _eventMap: A
}

// creating every type.. this is an example of one.
export type HTMLFormElementMeta = CreateElementMeta<
  "form",
  HTMLFormElement,
  HTMLFrameSetElementEventMap
>

// Union of ALL these meta types
type AllElementMeta = HTMLFormElementMeta | HTML[Name]Element //...

// helper for matching types, in this case
//  filtering out mismatched tagNames

export type MatchTagName<R extends string> = AllElementMeta extends infer T
  ? T extends CreateElementMeta<R, infer E, infer A>
    ? CreateElementMeta<R, E, A>
    : never
  : never


// using said types on document.creatElement
declare function createElement<
  K extends meta.AllElementMeta["_tagName"],
  L extends meta.AllElementMeta["_tagName"]
>(
  tagName: K,
  options: { is: L }
): meta.MatchTagName<K>["_element"] & meta.MatchTagName<L>["_element"]
```

## Checklist

My suggestion meets these guidelines:

* [ ] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).

## Side Notes

- This is a breaking change, but unsure how it could be handled elegantly since Typescript doesn't follow the semantic versioning specification.
- There are some missing events like `pointermove` on `HTMLElement`. These should be updated. I'll post a new issue unless advised otherwise.
- Users using custom elements and custom events need a way to insert their own `Element <-> EventMap` pairs. This would probably be done by append their types to the global namespace.