Add reference target by dandclark · Pull Request #10995 · whatwg/html

dandclark · 2025-02-05T01:39:54Z

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 )
/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 )
/microdata.html ( diff )
/parsing.html ( diff )
/popover.html ( diff )
/scripting.html ( diff )
/tables.html ( diff )

dandclark · 2025-03-18T00:37:25Z

@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 · 2025-03-19T00:49:42Z

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.

This concept is used to propagate events into the source's tree under certain circumstances.

lukewarlow

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

dandclark · 2025-08-06T21:38:26Z

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 · 2025-08-06T21:42:24Z

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---- · 2025-09-01T17:10:30Z

-  <span>tree</span>.</p>
+  a valid <span>single element reference</span> attribute
+  <span data-x="single-element-reference-refers-to">referring to</span> a <code>form</code>
+  element.</p>


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

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

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.

…ibute concepts.

…d make some tweaks in the Reflection section

…d attr target element(s) and unresolved attr target element(s)

…atting.

…ndclark/reference-target

dandclark · 2026-05-19T21:02:58Z

@annevk , @keithamus, @smaug----, this is ready for another round of review. I'd like to see if Chromium can ship this soon, so I want to make sure any remaining concerns are captured first. Thanks!

Note that I've incorporated the event propagation change discussed in WICG/webcomponents#1098 into this PR.

cc @alice

annevk · 2026-05-20T15:30:11Z

-  <code>Element</code>, then with <var>attr</var> being the <span>reflected content attribute
-  name</span>:</p>
+  <p>If a <span>reflected IDL attribute</span> has the type <code>Element</code>, then with
+  <var>attr</var> being the <span>reflected content attribute name</span>:</p>


Even if we remove inheritance I'm pretty sure we have to handle ?.

annevk · 2026-05-20T15:33:14Z

  slot (or map of additional fields) is required to properly specify this.</p>

+  <p>The <code data-x="dom-ToggleEvent-source">source</code> attribute defines the <span
+  data-x="concept-event-source">source</span> for a <code>ToggleEvent</code>.</p>


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

Acknowledged. I'll work on this.

…ustom element registry)

…e value

annevk · 2026-05-29T08:38:10Z

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.

Currently if a shadow root's reference target doesn't match any ID in the shadow, any element-reflecting IDL attributes (e.g. popoverTargetElement) referring to the shadow host will return null. Recent thinking in [1] and the current state of the spec PR [2] is that these should still reflect the shadow host, same as if the reference target pointed to a matching element. Update the Chromium implementation and tests to match this updated behavior. As it turns out, this also slightly simplifies the implementation. [1] WICG/webcomponents#1114 [2] whatwg/html#10995 Bug: 346835896 Change-Id: Ic321d5dffc1800fc081e9edfbb46524acc63a8be

Currently if a shadow root's reference target doesn't match any ID in the shadow, any element-reflecting IDL attributes (e.g. popoverTargetElement) referring to the shadow host will return null. Recent thinking in [1] and the current state of the spec PR [2] is that these should still reflect the shadow host, same as if the reference target pointed to a matching element. Update the Chromium implementation and tests to match this updated behavior. As it turns out, this also slightly simplifies the implementation. [1] WICG/webcomponents#1114 [2] whatwg/html#10995 Bug: 346835896 Change-Id: Ic321d5dffc1800fc081e9edfbb46524acc63a8be Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7883837 Reviewed-by: Mason Freed <masonf@chromium.org> Commit-Queue: Dan Clark <daniec@microsoft.com> Cr-Commit-Position: refs/heads/main@{#1638691}

dandclark · 2026-05-29T23:51:15Z

@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.

Currently if a shadow root's reference target doesn't match any ID in the shadow, any element-reflecting IDL attributes (e.g. popoverTargetElement) referring to the shadow host will return null. Recent thinking in [1] and the current state of the spec PR [2] is that these should still reflect the shadow host, same as if the reference target pointed to a matching element. Update the Chromium implementation and tests to match this updated behavior. As it turns out, this also slightly simplifies the implementation. [1] WICG/webcomponents#1114 [2] whatwg/html#10995 Bug: 346835896 Change-Id: Ic321d5dffc1800fc081e9edfbb46524acc63a8be Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7883837 Reviewed-by: Mason Freed <masonf@chromium.org> Commit-Queue: Dan Clark <daniec@microsoft.com> Cr-Commit-Position: refs/heads/main@{#1638691}

annevk · 2026-05-30T06:07:25Z

@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 changed the title ~~Add shadowrootreferencetarget attribute to template~~ Add reference target Feb 6, 2025

rniwa mentioned this pull request Feb 14, 2025

Add support for referenceTarget. WebKit/WebKit#39742

Merged

This was referenced Mar 7, 2025

Add reference target to shadow root whatwg/dom#1353

Open

Make reference target non-tentative web-platform-tests/wpt#51213

Draft

Editorial: Point to "element reference attribute" definitions in HTML for IDREF attributes w3c/aria#2474

Draft

dandclark requested review from annevk and domenic March 18, 2025 00:17

dandclark marked this pull request as ready for review March 18, 2025 00:30

rahimabdi mentioned this pull request Mar 23, 2025

Investigate changing ID-based WAI-ARIA value types due to referenceTarget w3c/aria#2487

Open

dandclark mentioned this pull request Mar 27, 2025

Reference Target: Should the form and list JavaScript attributes return the host element? WICG/webcomponents#1072

Closed

Add the concept of an event source.

4b2dd5e

This concept is used to propagate events into the source's tree under certain circumstances.

lukewarlow suggested changes Jul 31, 2025

View reviewed changes

Comment thread source Outdated

Comment thread source

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

dandclark requested a review from lukewarlow August 6, 2025 21:37

lukewarlow requested review from lukewarlow and removed request for lukewarlow August 6, 2025 21:41

keithamus suggested changes Aug 28, 2025

View reviewed changes

Comment thread source

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source