feat(types): add hidden helper to make inferring element types better @W-18442478

[wjhsf]

Details

When rendering an LWC component, the component instance and element instance are two connected but distinct objects. The component instance inherits from LightningElement, while the element is an instance of HTMLElement with a few additional properties. Those properties are the @api-decorated properties from the component instance.

When the class in the following example gets used, the component instance would have two props, exposed and internal. The element instance only has one, exposed.

class Example extends LightningElement {
  @api exposed = 'hello'
  internal = 'secret'
}

Because component authors create components, but largely consume elements, we added a new helper type in LWC v7.0.0 to bridge the gap. The new LightningHTMLElement type accepts a component interface and returns the corresponding element interface. However, it has a critical limitation. There is no way, in TypeScript, to distinguish decorated properties from non-decorated properties. And so, by default, LightningHTMLElement returns an interface with all properties defined on the component, not just @api-decorated properties.

const example = createElement('c-example', { is: Example });
example.exposed satisfies string // ✅
example.internal satisfies string // ❌ not a type error, but it should be!

The workaround originally provided for this was to explicitly provide the correct interface.

createElement<{ exposed: string }>('c-example', { is: Example });
this.querySelector('c-example') as LightningHTMLElement<{ exposed: string }>

However, this approach is limited, as it must be done for every single usage of createElement/LightningHTMLElement. More importantly, it requires the component consumer to provide the interface, rather than the component author. Thus, this PR introduces an new hidden/"fake" property that components can use. If a component defines __lwc_public_property_types__, then the type from that property is used as the public interface. This new property is "fake", in that it only exists as a hint to the type system; it never has a value at runtime. And it's "hidden" because it's not part of the public LightningElement interface, it's just sniffed by the helper type.

class Example {
  @api exposed = 'hello'
  internal = 'secret'
  __lwc_public_property_types__?: { exposed: string }
}

const example = createElement('c-example', { is: Example });
example.exposed satisfies string // ✅
example.internal // ✅ type error, as expected!

Closes #4292.

Does this pull request introduce a breaking change?

• 😮‍💨 No, it does not introduce a breaking change.
• 💔 Yes, it does introduce a breaking change.

Does this pull request introduce an observable change?

• 🤞 No, it does not introduce an observable change.
• 🔬 Yes, it does include an observable change.

GUS work item

[jhefferman-sfdc]

Such a beautiful description, thank you!