Adds experimental “decorators” interface.

[theengineear]

The TC39 proposals for JavaScript decorators and decorator metadata have
made their way to stage 3. The next step is for browsers to begin
implementing. It is not an “if” anymore, it is a “when”.

This means that it’s time for us to explore what ergonomic improvements
might be unlocked by enabling interoperation with these new interfaces.

Some important notes:

• We could ship this now (only integrator code requires new syntax).
• The new interface should be more idiomatic.
• We should be able to delete some invented concepts entirely.

Closes #346.

[theengineear]

Spent some time planning and implementing this (not going to push the implementation up just yet though). I think we could reasonably ship this as an experimental opt-in in 2.x without breaking anything. I also don’t think there’s any real urgency to delete the current interface as they work exactly the same in your markup — the change is all about the authoring and debugging experience.

I mention it a bunch in the “DECORATORS.md” document — but I really like how…

1. More of the integration code becomes idiomatic JavaScript.
2. We get to delete more of our invented abstractions (think properties and internal proxy objects).

[theengineear]

Here’s one example that is actually pretty amazing when you dig into it:

1. We are accessing a property right on the host. Which is the right mental model.
2. But, that property is completely integrated with the x-element machinery (e.g., invalidation, compute, reflect, observe, etc).
3. And… just like you expect, you can access private members because we’re in the same lexical scope (i.e., host.#privateThing just works like you would expect).
4. And perhaps most importantly… if you tell your IDE that host is of type TestElement — you get all the intellisense. If it was an instance method… your IDE would do this completely for free, but we need to strike a delicate balance here.

[theengineear]

Even with a fair amount of extra commentary (which will be removed, tightened) — we ended up with fewer lines of code here. That makes some sense because we deleted the concept of the internal proxy and deleted the properties proxy.

And, we end up actually supporting more features without needed to try (e.g., you can pass listener options directly to the @listener decorator). Also (and we will want to talk about this) — inheritance kinda just works now — for example #foo declared on a parent class is truly independent of a #foo declared on a child class (just like you would expect in regular class inheritance). And, you don’t need to redeclare a public field1 in a child class to use it idiomatically.