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]

Do you remember the case(s) when composed was fiddled with in the past?

I think we changed it for UI events. And more recently we weren't sure with these toggle events.

---

I fixed quite a few issues with this PR. Further review welcome. The outstanding issue is the synthetic events. It seems we should align them with precedent and have the constructors initialize the relatedTarget concept correctly.

[dandclark]

Thanks for taking the time @annevk. I'm going to be out on vacation next week but will make the change for synthetic events when I get back.

[smaug----]

One thing I haven't checked in tests: aria-labelledby and non-trivial DOM mutations in multiple levels of nested Shadow DOMs. (Support for aria-labelledby is one thing missing currently in Gecko's referenceTarget implementation)

[dandclark]

• I commented above about a potential approach for having the constructors set relatedTarget for synthetic events. @annevk if that seems reasonable I'll make those changes.
• @smaug---- there's tests for aria-labelledby at shadow-dom/reference-target/tentative
  /aria-labelledby.html, and shadow-dom/reference-target/tentative
  /dom-mutation.html covers interesting DOM mutation scenarios that include mutations across multiply-nested shadow roots.