Add reference target

[dandclark]

Reference Target allows authors to specify an element inside a shadow root to be the target of any ID references referring to the host element. This would enable IDREF attributes such as for and aria-labelledby to refer to elements inside a component's shadow DOM while maintaining encapsulation of the internal details of the shadow DOM.

See the reference target explainer.

At a high level, the spec change consists of these parts:

• Define the concept of "resolving the reference target" on an element, following an IDREF from a host element to its target in the shadow, and potentially recursing.
• Update the get-the-attr-associated-element algorithm (and its array-of-elements form) to follow reference target.
• Centralize the definitions of ID reference attributes and list-of-ID-reference attributes as "element reference" and "set of element reference" attributes instead of repeating these definitions throughout the spec.
• Update uses of ID throughout the spec, where applicable, to use the new reference-target-aware get-the-attr-associated-element.
• Avoid exposing reference target elements in shadows from element-returning IDL properties by retargeting the result before returning.

See also the corresponding whatwg/dom#1353 which adds the definition of reference target used in this PR.
 

• At least two implementers are interested (and none opposed):
  • Chromium is positive (I'd like to ship it there)
  • Reference Target for Cross-Root ARIA mozilla/standards-positions#1035 (Positive)
  • Reference Target for Cross-Root ARIA WebKit/standards-positions#356 (no position stated yet)
• Tests are written and can be reviewed and commented upon at:
  • https://wpt.fyi/results/shadow-dom/reference-target/tentative?label=experimental&label=master&aligned (still tentative)
  • PR to make non-tentative: Make reference target non-tentative web-platform-tests/wpt#51213
• Implementation bugs are filed:
  • Chromium: https://issues.chromium.org/issues/346835896/
  • Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=1952585
  • WebKit: https://bugs.webkit.org/show_bug.cgi?id=285634
• Corresponding HTML AAM & ARIA in HTML issues & PRs: Editorial: Point to "element reference attribute" definitions in HTML for IDREF attributes w3c/aria#2474
• MDN issue is filed: Create documentation for Reference Target mdn/mdn#832
• The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

---

/common-dom-interfaces.html ( diff )
/common-microsyntaxes.html ( diff )
/document-lifecycle.html ( diff )
/dom.html ( diff )
/form-control-infrastructure.html ( diff )
/form-elements.html ( diff )
/forms.html ( diff )
/iframe-embed-object.html ( diff )
/index.html ( diff )
/indices.html ( diff )
/infrastructure.html ( diff )
/input.html ( diff )
/interaction.html ( diff )
/interactive-elements.html ( diff )
/links.html ( diff )
/microdata.html ( diff )
/nav-history-apis.html ( diff )
/parsing.html ( diff )
/popover.html ( diff )
/scripting.html ( diff )
/tables.html ( diff )

[dandclark]

@annevk, @domenic, this isn't quite ready to land yet as there are still a few open questions to sort out (at least WICG/webcomponents#1087 and WICG/webcomponents#1093), plus missing implementor positions. But I don't expect most of the mechanics in this PR to change, so I think it would be great to get feedback on whether the approach we've used here is agreeable.

See also whatwg/dom#1353

Thanks!

[alice]

There's also a WIP PR against ARIA to account for these changes: w3c/aria#2474

There are some open questions being discussed there on exactly how to refer to the HTML concepts, since ARIA needs to be language-independent, but it will certainly refer to these spec concepts in some form.

[lukewarlow]

This should be updated to make use of the new [Reflect] syntax.

[dandclark]

This should be updated to make use of the new [Reflect] syntax.

Thanks @lukewarlow! Fixed now (it wouldn't let me merge the suggestions directly due to merge conflicts).

[lukewarlow]

I'm not sure how GitHub actually lets you dismiss change suggestions but consider this me dropping my change suggestions as they've been resolved :)

[keithamus]

I've done an initial review pass, got about half way, but I thought I'd provide my review commentary so far because I think if I continue I may end up repeating themes.

Some meta commentary:

• I think another formatting pass needs to be done.
• I am a little worried about the retargeting steps, I wonder if this can be simplified to avoid retargeting and to resolve a reference target where necessary.

[smaug----]

This isn't perhaps super clear. I think this means that the final element from single element reference should be a form element

[alice]

That's right. I'm not really sure of a clearer way to put it.

[annevk]

I wonder if this all works well for the Developer Edition of the standard as now we're phrasing conformance requirements in terms of algorithms aimed at implementers?

[alice]

I had to apply all the code suggestions manually, because I foolishly pushed my changes before I'd applied them.

[annevk]

How does this work if we say it has to be Element above? (Not the only occurrence it seems.)

[dandclark]

I think it was a mistake for the type to be Element above; I've changed it to Element?. So that should fit with the usage here and elsewhere.

[annevk]

I think you misunderstood my comment here. This was specifically talking about the mismatch between Element and HTMLElement.

[dandclark]

Ah, sorry, I understand now.

This (and the other IDL form attributes like it) isn't defined as a reflecting attribute, so it doesn't depend on the "If a reflected IDL attribute has the type Element?" algorithm, so the type doesn't need to match with that. This has its own definition from further down in the spec, which this PR also modifies to be:

Listed form-associated elements except for form-associated custom elements have a form IDL attribute, which, on getting, must return the result of retargeting the element's form owner against the element, or null if there isn't a form owner.

I think in practice this would always end up being an HTMLElement, since it will either be the actual HTMLFormElement or it'll be a shadow host due to retargeting, and currently only HTMLElement can be a shadow host due to the namespace check in step 1 of attach a shadow root.

But on the other hand:

• It's confusing for this to be HTMLElement since the related algorithms all deal in Elements
• Non-HTMLElements can be shadow hosts in Blink due to an apparently-longstanding bug
• Maybe someday we'll want to deliberately allow certain non-HTML-elements to be shadow hosts.

So all-in-all you're probably right that these should just be Element. I've updated all the occurrences.

[annevk]

This is too much action-at-a-distance. We need to actually define this at dispatch time.

[dandclark]

Acknowledged. I'll work on this.

[annevk]

Alice, Jake, Olli, and I discussed the event model again. Here's the concrete proposal:

• For events that have a non-null source-like concept (such as source or submitter), we set event's relatedTarget concept to that value and we set composed to true at the time we pass the event to the dispatch algorithm. (This is roughly comparable to the current proposal except that intermediate shadow roots are no longer skipped. See https://mozilla.pettay.fi/composed-events-dispatch.html for a visualization.)
• For events with a source-like concept, the IDL getter for that concept now needs to return event's relatedTarget concept.

[dandclark]

@annevk I think this basically makes sense. There are a couple details I'm unclear on about setting the event to composed.

• It seems like there is some additional compatibility risk to this. For example, consider the case when the submit event is fired on a form due to a button being clicked, with no reference target involved, so the button and form are in the same tree. There would be no change to how the event bubbles, since both target (the form) and relatedTarget (the button) are in the same tree, but event listeners on the form would still see event.composed == true.
  • Maybe we can avoid this by only setting composed if target and relatedTarget are not in the same tree, which would mean that reference target was being used, which removes the compat concern since it's a new thing?
• When you say "we set composed to true at the time we pass the event to the dispatch algorithm", when exactly does this mean? Usually composed gets set from the HTML spec when it calls fire an event, so maybe we could do it at that time when the HTML spec calls fire an event for Command, Toggle, and Submit events. But it sounds like your idea might have been that we'd set composed inside the DOM spec algos either at the beginning of dispatch or right before dispatch, in fire an event? This might be OK but seems like it could cause compat issues for events like mouseenter that already use relatedTarget but are not composed; we’d have to exclude them from the change somehow like by scoping the change to specific event types.

[annevk]

@dandclark thanks, for 1) I think our assessment is that websites are highly unlikely to rely on the composed value as we have been able to fiddle with it in the past. For 2) we meant when initializing the specific events under discussion in HTML. Not as a generic solution for all events as that would indeed clash with existing relatedTarget consumers.

Fire an event does run into whatwg/dom#1328 which I think @keithamus wanted to look into, but should probably not block this. Maybe we want to add a source comment (<!-- ... -->) though.

[dandclark]

@annevk Ok, I pushed those changes to this and the DOM spec PR (whatwg/dom#1353).

In these changes I'm trying to draw a distinction between Event's internal relatedTarget concept and the relatedTarget attribute that gets exposed in other specs like https://w3c.github.io/uievents/#dom-focusevent-relatedtarget. So I changed fire an event to take a separate relatedTarget parameter that sets the internal relatedTarget concept, rather than reusing the existing machinery that would set it as an attribute. Not sure if that's the right approach to take us in the direction of fixing whatwg/dom#1328 or if I should just have all the "fire an event" calls initialize relatedTarget as another attribute on the event for now.

[annevk]

How does this work for synthetic events. Should we remove the source member from IDL or do we allow an explicitly-set source to win somehow? (Same for the other events.) Needs test coverage as well.

[dandclark]

The simplest thing could be that when source is set on a synthetic event (new CommandEvent('command', {source: someElement} etc), it sets the actual Event relatedTarget concept, just like with non-synthetic events that have a source. So it could affect the event path, and could be retargeted during dispatch.

The downside of this would be compatability. Devs can already create synthetic events today without the use of reference target whose dispatch behavior would be affected by this. Are there other reasons not to prefer that approach?

If that sounds bad due to the compat issue or for other reasons, seems reasonable to have something like an explicitly-set source that doesn't touch relatedTarget but that could be reflected in the IDL attribute.

[annevk]

I think making relatedTarget a (named) parameter is a good idea.