feat: enable face lifecycle methods and wrap ElementInternals in a proxy

[jmsjtu]

Details

This PR exposes the face lifecycle methods as described in the Element Internals and Form Association.

Note that exposing ElementInternals was already done in #3670.

These lifecycle methods are designed to only work with native lifecycle enabled and only for native shadow or light DOM.

Does this pull request introduce a breaking change?

• ✅ No, it does not introduce a breaking change.

Does this pull request introduce an observable change?

• ✅ No, it does not introduce an observable change.

GUS work item

W-13818672

[nolanlawson]

Overall LGTM, just a few small nitpicks!

[jmsjtu]

@nolanlawson The PR is ready for another round of reviews!

Also, moving forward with the ElementInternals enablement, I think we may need to do some additional work on how to handle setting the formAssociated value.

Since formAssociated = true is always set on the UpgradableConstructor when the component is placed inside a form element, the form property on ElementInternals will have a value regardless of whether formAssociated was set on the LWC.

Example:

<form>
    <x-foo></x-foo>
</form>

import { LightningElement, api } from 'lwc';

export default class extends LightningElement {
    @api
    internals = this.attachInternals();
}

In contrast, the browser behavior shows an exception when it's not set:
DOMException: Failed to read the 'form' property from 'ElementInternals': The target element is not a form-associated custom element.

Once we remove the UpgradeableConstructor and directly invoke the LWC constructor we will break any customers that create a dependency on the form being associated with ElementInternals when formAssociated is not set.

I think we can handle this in a few ways:

1. Once the UpgradeableConstructor is removed, we could always set the formAssociated = true in the LightningElementConstructor.
2. We could create some additional logic for now to overwrite the value of form on the ElementInternals object when attachInternals is called and replace it with an exception.
3. Enforce setting formAssociated when attachInternals is set until UpgradeableConstructor has been removed (throw an error?).

Wanted to get your thoughts on how we should handle this moving forward.

This might be more straightforward or complicated depending on the Locker/LWS pivot implementation.

[nolanlawson]

@jmsjtu Great catch. I think if we do nothing, then people might end up taking a dependency on elementInterals.form being available regardless of whether they set formAssociated or not.

I hate doing this kind of thing, but my preference here is to return a Proxy object rather than the actual ElementInternals, and to mimic the browser behavior when the form getter is called. Sadly I cannot think of a better solution.

Are there any other properties on elementInternals that behave this way?

[jmsjtu]

Discussed with @nolanlawson and we will need to create a proxy for the following instance properties:

• ElementInternals.form
• ElementInternals.willvalidate
• ElementInternals.validity
• ElementInternals.validationMessage
• ElementInternals.states

Additionally, there's currently a bug in Safari with formAssociated causing non-focusable elements to become focusable.

This is causing a karma test failure.

[AllanOricil]

This feature is cool. Nice job

[nolanlawson]

Additionally, there's currently a bug in Safari with formAssociated causing non-focusable elements to become focusable.

Let's ignore Safari in the test for now. We can also add a comment with a TODO saying to keep an eye on the WebKit bug.

[jmsjtu]

Removed this TODO since #2566 has been fixed.

[nolanlawson]

Suggested change

	let formAssociated = superDef.formAssociated;
	if (!isUndefined(ctorFormAssociated)) {
	formAssociated = ctorFormAssociated;
	}
	const formAssociated = Boolean(superDef.formAssociated);

I looked into it, and it seems that the browser's treatment of formAssociated is based on truthiness. It would make our internal code simpler if we set formAssociated to either true/false in one place in the code, so that we could rely on it being a boolean everywhere else.

[nolanlawson]

Or undefined | boolean is also fine – just that we don't actually know what type superDef.formAssociated is right? The user could put static formAssociated = 'yolo'.

[nolanlawson]

I have a nitpick about types, but overall this looks great to me.

[AllanOricil]