Intent to Ship: Reference Target

21 views
Skip to first unread message

Daniel Clark

unread,
7:22 PM (1 hour ago) 7:22 PM
to blin...@chromium.org
Contact emails

dan...@microsoft.com, leo...@microsoft.com

Explainer

https://github.com/WICG/webcomponents/blob/gh-pages/proposals/reference-target-explainer.md



Specification

https://github.com/whatwg/html/pull/10995, https://github.com/whatwg/dom/pull/1353

Summary

Reference Target enables ID attributes like <label for>, 'aria-labelledby', 'popovertarget', and 'commandfor' to be forwarded to elements inside a component's shadow DOM, while maintaining the shadow's encapsulation of its internal state. When a shadow host specifies an element in its shadow tree to act as its reference target, all ID references pointing to the shadow host are forwarded to the reference target element instead.


For example, here the <label>’s “my-checkbox” ID reference is forwarded to the element in the shadow with the ID “real-checkbox":

 

<label for="my-checkbox">Click me to toggle checkbox</label>

<custom-checkbox id="my-checkbox">

<template shadowrootmode="open" shadowrootreferencetarget="real-checkbox">

<input id="real-checkbox" type="checkbox">

</template>

</custom-checkbox>

 

Reference target can be set declaratively like in the above example, or in JavaScript with ShadowRoot's 'referenceTarget' property.

Blink component

Blink>DOM>ShadowDOM

Web Feature ID

referencetarget

Motivation

Shadow DOM presents a problem for accessibility: there is not a way to establish semantic relationships between elements in different shadow trees (such as via 'aria-labelledby'). This limits the ability to design web components in a way that works with accessibility tools such as screen readers. The ARIAMixin IDL attributes (https://w3c.github.io/aria/#ARIAMixin) are a partial solution to the problem; however, they lack the ability to create a reference "into" a shadow tree from the outside. Reference Target is a solution to that missing piece of the problem.

 

In addition to the issues with accessibility, ID attributes like 'popovertarget' and 'commandfor' can’t be used to refer to elements inside a shadow root without reference target.

Initial public proposal

https://github.com/WICG/aom/pull/207

TAG review

https://github.com/w3ctag/design-reviews/issues/961

TAG review status

Issues addressed

Origin Trial Name

Reference Target for Cross-Root ARIA

Chromium Trial Name

ShadowRootReferenceTarget

WebFeature UseCounter name

WebDXFeature::kDRAFT_ReferenceTarget

Risks



Interoperability and Compatibility

The interoperability risk is low since engineers from the other browser engines have been active in spec discussions about the feature.

 

This feature makes a change to the Toggle, Command, Interest, and Submit events that presents a small compatibility risk. These events each have a 'source'/'submitter' property that's set to the element triggering the event, e.g. the button element clicked to open a popup. With reference target this element can now be in a parent shadow tree relative to the event is fired. Per discussion in https://github.com/WICG/webcomponents/issues/1098 there was a desire to have the event's dispatch path include the source/submitter's tree. This is done by setting these events' internal relatedTarget (https://dom.spec.whatwg.org/#event-relatedtarget) to their 'source'/'submitter'

and making the event composed when that relatedTarget is non-null. When used with reference target this causes the event path to include a 'source'/'submitter' in a parent shadow.

 

When used without reference target, there is no change to these events' event paths (since the source/submitter can never be in a parent shadow, therefore the relatedTarget will be in the same tree as the target, therefore the event won’t dispatch in the parent shadow per the current event dispatch algorithm). But, the 'composed' property on the event will be set to true. This has already been changed in the past for Command and Interest events (https://chromium-review.googlesource.com/c/chromium/src/+/6505682, https://chromium-review.googlesource.com/c/chromium/src/+/7797864), and there's also history of changing these for Mouse events (https://chromium-review.googlesource.com/c/chromium/src/+/4563502), so I'm optimistic that this won't cause breakage. Most usage on Github (https://github.com/search?q=%2Fevent%5C.composed%5B%5EP%5D%2F&type=code) is either conditional on 'bubbles' also being true, which is false for the events in question, or is or is specific to mouse events which aren't affected here.

Gecko: Positive (https://github.com/mozilla/standards-positions/issues/1035)

WebKit: No signal (https://github.com/WebKit/standards-positions/issues/356)

Web developers: Positive 

We ran an Origin Trial for the feature back in 133-135 but didn’t get much developer uptake at the time. I attribute this to the difficulty of poylfilling — see Activation section. We’ve since worked closely with developers to ensure that the API meets their needs and they’ll be able to adopt it.

 

Activation

This is a difficult feature to polyfill since ID reference attributes cannot pierce into shadow roots without it. So there's no way for a polyfill to enable the capability that reference target enables. My hope is that this will be mitigated by other browsers shipping the feature. Gecko is positive, I've been discussing the spec changes with engineers from both Gecko and WebKit, and Gecko and WebKit both have prototype implementations.

 

There is already brief MDN documentation:

https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootreferencetarget

https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot#shadowroot.referencetarget


There has sometimes been confusion about what scenarios the feature unlocks, e.g. some developers assumed it directed ID references *out* of a shadow root rather than *into* a shadow root. I'll ensure that we have good documentation available including examples like those in https://microsoftedge.github.io/Demos/reference-target/. The MDN docs issue for the feature is still open at https://github.com/mdn/content/issues/43453.

WebView application risks

None



Debuggability

No specific DevTools support is expected to be necessary. Existing DevTools support for features used with reference target will continue to work. For example, the accessibility tree viewer can be used to check that an 'aria-labelledby' attribute is applied correctly even when it's used cross-shadow-DOM with reference target.

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

Yes

Is this feature fully tested by web-platform-tests?

Yes: https://wpt.fyi/results/shadow-dom/reference-target

Flag name on about://flags

No information provided

Finch feature name

ShadowRootReferenceTarget

Rollout plan

Will ship enabled for all users

Requires code in //chrome?

False

Tracking bug

https://issues.chromium.org/issues/346835896

Availability expectation

I've received positive engagement on the spec PR from WebKit and Gecko engineers, and the feature is prototyped in both of those engines. So I'm optimistic that they will follow in supporting this feature, though there is no official commitment of support.

Adoption expectation

We are working with a developer partner who plans to adopt the feature once it's shipped.

Non-OSS dependencies

None

Estimated milestones

Shipping on desktop

151

Origin trial desktop first

133

Origin trial desktop last

135

Shipping on Android

151

Shipping on WebView

151



Anticipated spec changes

No breaking changes are expected.

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5188237101891584?gate=5152828586196992

Links to previous Intent discussions

Intent to Prototype: https://groups.google.com/a/chromium.org/g/blink-dev/c/CEdbbQXPIRk/m/U43spqbKAgAJ
Intent to Experiment: https://groups.google.com/a/chromium.org/g/blink-dev/c/C3pELgMqzCY/m/Lpb6DkueAQAJ


Reply all
Reply to author
Forward
0 new messages