Reference Target: Should the `form` and `list` JavaScript attributes return the host element?

[behowell]

This question was brought up by @mfreed7 in #1066 (comment).

In the JavaScript attributes that reflect Element objects section of the Reference Target Explainer, it describes how JavaScript attributes should return the host element, and not their reference target directly.

There are two attributes where this doesn't work today, because they are expected to return a specific element type:

• The .form attribute always returns a HTMLFormElement.
• The .list attribute always returns a HTMLDataListElement.

In the following example, the submit button is successfully linked to the <form id="real-form"> via the reference target. The question is what should the .form JS attribute return?

<button id="submit" type="submit" form="fancy-form">Submit</button>
<fancy-form id="fancy-form">
  <template
    shadowrootmode="open"
    shadowrootreferencetarget="real-form"
  >
    <form id="real-form"></form>
  </template>
</fancy-form>

<script>
  const submit = document.getElementById("submit");
  console.log(submit.form); // << What does this log?
</script>

There are a few possible options:

1. The .form and .list always return null when used with a reference target. This way they never return something that's not the expected type.
2. Update .form and .list to be able to return any HTMLElement if (and only if) it has a reference target set.

• Although changing the return type for an attribute seems to have the possibility of breaking existing web pages, option 2 would only apply to net-new scenarios, and no web pages would be affected until they start using reference targets.

--

If we go with option 2, then that opens a secondary question that is related to the question posed in #1071:

What should it return if the reference target is not a valid HTMLFormElement/HTMLDataListElement? For example:

<button id="submit" type="submit" form="not-a-form">Submit</button>
<x-div id="not-a-form">
  <template
    shadowrootmode="open"
    shadowrootreferencetarget="real-div"
  >
    <div id="real-div"></div>
  </template>
</fancy-form>

<script>
  const submit = document.getElementById("submit");
  console.log(submit.form); // << What does this log?
</script>

The options are:
2a. It returns null. Even though it refers to a valid host element, which has a valid reference target, the target element is the wrong type and there is no underlying association. This is the same as if you set the form="" attribute to something that's not a <form>.
2b. It returns the host element. Presumably this would only happen if we went with Option 1b from #1071.

[behowell]

I like option 2a the best, as long as changing the return type of those attributes can be done in a way that doesn't break the web.

[dandclark]

The behavior of the HTMLLabelElement.control property should also follow whatever is decided here regarding 2a/2b. Its type is already HTMLElement, but the underlying association that it reflects can only be with a labelable element. In the Blink reference target prototype the behavior currently implemented for HTMLLabelElement.control is 2a.

[sorvell]

This is really thorny since some previous invariant cannot be satisfied. Either .form returns null in a case that this is unexpected (the button does submit the form), or it returns the wrong type and any code that depends on this being an HTMLFormElement could break.

Option 3: Return the actual reference target element. This does not seem acceptable because it breaks encapsulation. I'm suggesting this as an option because the downside should be balanced against the downsides of the other options.

Option 4: Return a proxy of the reference target element that appears as if it has no parentNode, etc, and cannot otherwise gain access to its containing shadowRoot.

In the absence of these more exotic options being possible, I think just Option 1 returning null feels safest. Failing to find a form isn't great but returning an unexpected thing seems more likely to generate an exception..

[kyubisation]

I feel like returning null closes the door on having the potential of making it work.
e.g. if there is a common library that depends on .form being available, returning null requires implementing an alternative approach for custom elements.
However, returning the host has the potential of just working. Even if fancy-form does not initially work, the author of that component can make it compatible with HTMLFormElement as a later fix.

[sorvell]

I feel like returning null closes the door on having the potential of making it work.

On reflection, I think I agree with @kyubisation and #1066 (comment).

Returning the host is preferable, if possible, because it leaves the platform more open to future improvement.

If it returns null, then we must (likely) forever accept a new rule that you cannot use .form to know if a form will be submitted when you click a button.

[dandclark]

I feel like returning null closes the door on having the potential of making it work.

On reflection, I think I agree with @kyubisation and #1066 (comment).

I am coming around to see it this way too. It's a potentially breaking change either way (though only for sites that opt-in to using reference target), but returning the host provides more useful information, especially since #1071 seems to have reached a conclusion that an invalid reference target should return null. So checking if form/list are null would let devs determine whether the reference target points to a valid target or not.