[RRFC] Improve decorator support for JS users

[sorvell]

• [X ] I searched for an existing RRFC which might be relevant to my RRFC

Motivation

It's a major design goal of Lit to hew close to the web platform while at the same time providing excellent developer experience (DX). The use of decorators strongly contributes to the DX goal before they provide convenient, declarative configuration. However, although decorators are stage 3 and therefore will be included in the web platform, they have not shipped in any browser yet and therefore using them requires a polyfill like TypeScript or Babel which degrades. This degrades DX for developers who wouldn't otherwise use these tools.

To provide good DX for pure JS users, lit currently allows special declaration of reactive properties using the static get properties() { return {...}} class property.

However, the declarative configuration provided by Lit's other decorators are not supported, which is not ideal.

There is another motivation for this change: Lit 3.x has added support for stage 3 standard decorators in addition to supporting the previous abandoned stage 2 proposal. Unfortunately, the static get properties() code path is distinct from either the stage 2 or stage 3 decorator code. This creates a maintenance burden and has the potential to ship extra, unneeded code.

Proposal

Lit should provide a way to easily use all supported decorators without the need for a decorator polyfill. To do this, a decorate method could be added which takes the class constructor and a set of decorator instructions provided via a config object. This would be used in a class static block, which are supported in all current browsers.

The decorate method would use Lit's decorators behind the scene thus reducing code complexity. It should also use the stage 3 standard decorators to support eventual removal of the stage 2 decorator support. Lit's static get properties() feature should also be deprecated.

Example

https://lit.dev/playground/#gist=254582877f3a7fa416f069b7c284d4d4

export class MyElement extends LitElement {
  
  static {
    decorate(this, {
      customElement: 'my-element',
      property: {
        count: {type: Number}
      },
      query: {
        hi: '.hi'
      },
      eventOptions: {
        clickHandler: {once: true}
      }
    });
  }
//...

References

• n/a