[lit-element] Declarative event emitters

It would be convenient for ergonomics, documentation, React integration, and transpilers to be able to declare what events an element fires.

We could add a decorator (and static block for plain JS, like properties) that allows this by decorating event handler properties. The decorator would create accessors that use addEventListener under the hood.

TypeScript:

class MyElement extends LitElement {
  @event() onFoo!: (e: FooEvent) => any) | null;

  render() {
    html`<button @click=${this._onButtonClick}>Click Me</button>`;
  }

  _onButtonClick(e) {
    this.dispatchEvent(new FooEvent());
  }
}

interface HTMLElementEventMap {
  'foo': FooEvent;
}

JavaScript:

class MyElement extends LitElement {
  static events = {
    onFoo: {},
  };

  render() {
    html`<button @click=${this._onButtonClick}>Click Me</button>`;
  }

  _onButtonClick(e) {
    this.dispatchEvent(new FooEvent());
  }
}

See some similar previous discussion here: https://github.com/Polymer/lit-element/issues/808

[daKmoR]

many questions 😬 😅
how is onFoo connected to _onButtonClick or _onButtonClick? what would users of the component do? <my-element @onFoo=${}>?

[landrito]

To tie this back to the original proposal:

class MyElement extends LitElement {
  @event() onFoo!: (e: FooEvent) => any) | null;

  render() {
    html`<button @click=${this._onButtonClick}>Click Me</button>`;
  }

  _onButtonClick(e) {
    this.dispatchEvent(new FooEvent());
  }
}

interface HTMLElementEventMap {
  'foo': FooEvent;
}

The interface HTMLElementEventMap above is unnecessary for Events with string literal types for their type field. Assume FooEvent is declared as follows:

class FooEvent extends Event {
  readonly type!: 'foo';

  constructor() {
    super('foo');
  }
}

Furthermore I’d propose that the Decorator Options provided are specific to the Event in question. For example, the opts @ChristianUlbrich provided above could be updated to:

export type EventName<E extends Event | void = void> =
  E extends {type: infer TypeAttribute} ? TypeAttribute : string;

export interface EventOptions<E extends Event | void = void> {
  /**
   * A string custom event name to override the default.
   */
  eventName?: EventName<E>
}

const opts: EventOptions<FooEvent> = {
  // Expected Error: Type '"Bar"' is not assignable to type '"foo" | undefined'.
  eventName: 'Bar'
}

There is a problem though. Typescript doesn’t seem to support generic decorators very well meaning the type of the decorators target is not propagated to the decorator function: https://github.com/microsoft/TypeScript/issues/2607.