[meta] Add guidance on events and interfaces

[justinfagnani]

We would prefer that protocol are consistent when it comes to use of events and other interfaces. We should provide guidance to encourage this and help reviewers.

I would propose that the guidance include things like:

• Do not depend on specific implementations as part of a protocol. Define interfaces instead.
• Define interfaces in TypeScript
• Prefer Event subclasses over CustomElement
• Publishing an interface-only (.d.ts) package to npm can be useful for interop
• Publishing interoperability / conformance tests is great!
• Publishing a reference implementation is great too

[matthewp]

Prefer Event subclasses over CustomElement

First I've heard of this, what's the reason?

[justinfagnani]

CustomEvent would have been completely unnecessary if Event had been subclassable earlier. At this point it's just a quirk of web development's history.

But the big problem with CustomEvents is that the event dispatcher creates the event, its data and options, which leaves a lot of room for divergence and incompatibilities. You can overcome some of this with a factory function to ensure the events are created consistently, but then you're very close to an Event subclass anyway.

These are the things you want to specify in a protocol and make hard to deviate from in an implementation:

• Event name
• Options: bubble, cancelable, composed
• Properties

In an event subclass you can do this all in the constructor. You can also specify the whole API of the Event, not just the details object, and the ergonomics of creating and using events are better without having to use or think about the detail object. You also have a class that you can hang documentation on.

Defining an event is more verbose than not defining an event, but it's straightforward and declares the intention of the event. We'd have to specify this information for CustomEvents used in a protocol anyway, it'd just be a lot more ad-hoc:

/**
 * The `my-event` event represents something that happened.
 * We can document it here.
 */
export class MyEvent extends Event {
  static eventName = 'my-event';

  /** We can easily document properties */
  foo;

  /**
   * You can add properties over time without breaking.
   * If we used CustomEvent we'd have to advise that detail is always an object
   */
  bar;

  constructor(foo, bar) {
    // Since these are hard-coded, dispatchers can't get them wrong
    super(MyEvent.eventName, {bubbles: true, cancelable: true, composed: true});

    // users are forced to provide parameters. You can do validation here you can't do with
    // detail objects
    this.foo = foo;
    this.bar =  bar;
  }
}

Dispatching events is easier and safer. You don't have to know the event name or options, just the constructor signature. It mirrors built-in event usage too.

this.dispatchEvent(new MyEvent(foo, bar));

[Westbrook]

@justinfagnani is there a place in the repo where you could see us adding this information?