[Enhancement]: Strong typing of exposed Events

[michavie]

What is your suggestion?

My suggestion is to introduce strong typing for the details of CustomEvents in our developer API. This means we define & expose clear types for each event detail, improving type safety when developers are responding to these events.

Why is it important?

Strong typing, in supported environments, provides predictability, clarity, and type safety for developers, enhancing the overall developer experience.

How would you implement it?

Sketched out idea:

type MmlEventPositionEnterDetail = {
  elementRelative: ...
  documentRelative: ...
}

export type MmlEventPositionEnter = CustomEvent<MmlEventPositionEnterDetail>

new CustomEvent<MmlEventPositionEnterDetail>(positionProbeEnterEventName, {
  detail: {
    elementRelative: elementRelativePositionAndRotation,
    documentRelative: documentRelativePositionAndRotation,
  },
}),

So developers have type-safety when listening to events:

positionProbe.addEventListener("positionenter", (event: MmlEventPositionEnter) => {
    const { connectionId, elementRelative, documentRelative } = event.detail;
  });

---

Once such event detail types exist, they can be utilized by e.g. the React starter kit's type declarations (https://github.com/mml-io/mml-react-starter-project/blob/main/mml-document/src/declaration.d.ts) and others to provide a fully typed experience for developers. That sounds like many happy MML devs to me :)

---

On the implementation part, there are definitely non-trivial things to be considered, like pointed out by @MarcusLongmuir : #67 (comment)

Packages

No response

Extra details

This idea originated in the PR comments of #67