Intent to Ship: Element Reflection

[alice]

Contact emails
al...@igalia.com, mere...@chromium.org

Explainer
https://github.com/WICG/aom/blob/gh-pages/aria-reflection-explainer.md#reflecting-element-references

Specification
https://html.spec.whatwg.org/multipage/common-dom-interfaces.html#reflecting-content-attributes-in-idl-attributes:element
https://w3c.github.io/aria/#ARIAMixin

Summary
This feature allows for ARIA relationship attributes to be reflected in
IDL as element references rather than DOMStrings.

Note: This intent specifically concerns the ARIA attributes using
Element Reflection, i.e. the attributes in the ARIAMixin interface with
a type of Element or FrozenArray<Element>. popoverTargetElement, which
also uses Element Reflection, is already shipping in Blink and WebKit.

Blink component
Blink>DOM

TAG review
https://github.com/w3ctag/design-reviews/issues/134

TAG review status
Issues addressed

Risks

Interoperability and Compatibility

Gecko: Under consideration
https://github.com/mozilla/standards-positions/issues/200
https://bugzilla.mozilla.org/show_bug.cgi?id=1769586

WebKit: Shipped/Shipping
(https://developer.apple.com/documentation/safari-technology-preview-release-notes/stp-release-151)
Mentioned in STP release notes:
https://developer.apple.com/documentation/safari-technology-preview-release-notes/stp-release-151
Was shipped in Safari 16.4 but wasn't mentioned in release notes there.

Web developers: Requested by Web Component authors in particular as a
means to implement ARIA relationships for elements inside of Shadow DOM.

Activation
This feature is not completely polyfillable; ID references across shadow
root boundaries are not possible to implement on top of existing APIs.

WebView application risks
None

Debuggability
Developers can use console.log to access the value for IDL attributes
set via this API, and the Accessibility pane to confirm that the
attributes are correctly reflected in the accessibility tree.

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?
https://wpt.fyi/results/html/dom/aria-element-reflection.html tests that
the reflection part of the API works correctly.
WPT doesn't yet offer a way to test the relevant accessibility tree
mappings.

Flag name on chrome://flags
None

Finch feature name
None

Non-finch justification
None

Requires code in //chrome?
False

Tracking bug
https://crbug.com/981423

Measurement
Per-attribute UseCounters:
V8Element_AriaActiveDescendantElement_AttributeGetter
V8Element_AriaActiveDescendantElement_AttributeSetter
V8Element_AriaControlsElements_AttributeGetter
V8Element_AriaControlsElements_AttributeSetter (etc)

V8ElementInternals_AriaActiveDescendantElement_AttributeGetter
V8ElementInternals_AriaActiveDescendantElement_AttributeSetter
V8ElementInternals_AriaControlsElements_AttributeGetter
V8ElementInternals_AriaControlsElements_AttributeSetter (etc)

Estimated milestones
123 or 124

Anticipated spec changes
None

Link to entry on the Chrome Platform Status
https://chromestatus.com/feature/6244885579431936

Links to previous Intent discussions
Ready for Trial:
https://groups.google.com/a/chromium.org/g/blink-dev/c/yecxBLmRVQI/m/d7YOe_nYAgAJ

[Philip Jägenstedt]

Hi Alice,

For testing of these in WPT, do you have some details on what's missing? It's already possible to get the accessible name and role for an element:

https://web-platform-tests.org/writing-tests/testdriver.html#accessibility

I suspect that won't help, but there's an experimental/tentative API being proposed for testdriver.js here:

https://github.com/web-platform-tests/wpt/pull/43773

Would that allow this feature to be tested more fully?

Best regards,

Philip

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/865bf3bd2e6a58da9fc3424ed957ceee%40igalia.com.

[Vladimir Levin]

I wonder if you had any feedback from framework authors that use VDOM. For context, we were considering using element references for a different feature, and couldn't overcome the fact that when frameworks change DOM, sometimes Nodes and Elements are removed or reused for a different purpose than when initially constructed (ie the element that used to represent the first item in the list is now used to represent the third item in the list).

I realize that this is asking a question very late in the design process, but I'm just curious if that's a case that you considered and if so how you reasoned about it.

[Alice Boxhall]

On Thursday, February 1, 2024 at 4:01:32 AM UTC+11 Philip Jägenstedt wrote:

Hi Alice,

For testing of these in WPT, do you have some details on what's missing? It's already possible to get the accessible name and role for an element:

https://web-platform-tests.org/writing-tests/testdriver.html#accessibility

These attributes affect relationships between elements, which project into the accessibility tree in various ways. `aria-labelledby` does affect the accessible name, so we could write a test for that (which would actually go some way to demonstrating that these attributes affect the accessibility tree in general), but the remaining attributes affect things like accessible description computation (`aria-describedby`), accessibility tree structure (`aria-owns`), which element appears to have focus (`aria-activedescendant`), or how some assistive technology should provide hints to the user (`aria-flowto`, `aria-details`, `aria-owns`, `aria-errormessage`).

 

I suspect that won't help, but there's an experimental/tentative API being proposed for testdriver.js here:

https://github.com/web-platform-tests/wpt/pull/43773

Would that allow this feature to be tested more fully?

That would allow checking how tree structure is affected, so we could test at least one more attribute! I can't tell what other properties will be exposed in the tree, so I'm not sure about the rest.

[Alice Boxhall]

To be honest, no, we didn't take VDOM into account. 

I'd be curious to hear what specific cases you were running into difficulty with, but it does seem like these paradigms are fundamentally at odds with one another - if elements are unpredictably destroyed and recreated, then it seems like using the string ID-based version is going to be a better fit. This API is, at least, designed to work with using the `setAttribute()` version, in that setting the content attribute will cause any value set via the IDL attribute to be discarded (and vice-versa).

(VDOM has always made me anxious for similar reasons - if elements are unpredictably moved or destroyed, what happens if an assistive technology was visiting those nodes in the accessibility tree when that happens? But I have essentially no experience actually using it, so presumably that can be managed in practice.)

[Elsa Vega-Martinez]

Hello Alice,

I have no clue what you are talking about. This is all  technology and I have no clue of what it is, ma’am, so if you can explain this in plain English, I would appreciate it. 

Just for your information someone is emailing all of you and it is not me. Our you a Technology company are you guys hackers or are you guys helpers because I am absolutely actually I’m scared to see all this technology talk. Are you people tracking me I see there’s a thread and a lot of other things but I do not understand it. I’m sorry, but I do need an explanation because I am going to be turning in my phone to the police department because I am being stuck and I don’t know if it’s you people or somebody else so please if you can be kind and call me, I would appreciate it. 

Thank you,

Elsa

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/2e4f1290-a652-4901-9cba-2de31ea6ed26n%40chromium.org.

[Vladimir Levin]

The main use case for us was just matching elements automatically across DOM mutations with a caveat that we were using CSS, not attributes. We couldn't really get a sense of how stable our proposals were because of the VDOM type of reordering. It might be worthwhile for us to revisit that plan. I agree with you that I think your case is a lot better, since it affects attributes being set, instead of being some ephemeral state that the browser keeps track of. 

 

(VDOM has always made me anxious for similar reasons - if elements are unpredictably moved or destroyed, what happens if an assistive technology was visiting those nodes in the accessibility tree when that happens? But I have essentially no experience actually using it, so presumably that can be managed in practice.)

I also agree with this sentiment. It seems like we want to rely on the persistence of elements and their identity, but at the same time there are a lot of optimized frameworks that are fast because they don't.

[Elsa Vega-Martinez]

Look I don’t know what you guys are talking about. This is gonna be the last time I’m asking you give me a call right now or I am delivering this to the police department. I’m not playing around anymore I do not know who you people are. I don’t know if you guys are tracking something selling something delivering something you don’t even know who I am ANNA and I somebody is sending you these messages and it’s not me and I’m giving you my phone number area code 559-871-6945. 

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CADsXd2Nixz41KJKXtd7TWQOrS%3DBWVOjSVKQJfqF_9OH6Cjqomg%40mail.gmail.com.

[Domenic Denicola]

Very exciting to see this!

On Thu, Feb 1, 2024 at 12:10 AM alice <al...@igalia.com> wrote:

Contact emails
al...@igalia.com, mere...@chromium.org

Explainer
https://github.com/WICG/aom/blob/gh-pages/aria-reflection-explainer.md#reflecting-element-references

Specification
https://html.spec.whatwg.org/multipage/common-dom-interfaces.html#reflecting-content-attributes-in-idl-attributes:element
https://w3c.github.io/aria/#ARIAMixin

These specs are incompatible with each other, because https://github.com/w3c/aria/pull/1876 has not yet been merged. Do you think it'll be possible to get that merged soon?

 

Summary
This feature allows for ARIA relationship attributes to be reflected in
IDL as element references rather than DOMStrings.

Note: This intent specifically concerns the ARIA attributes using
Element Reflection, i.e. the attributes in the ARIAMixin interface with
a type of Element or FrozenArray<Element>. popoverTargetElement, which
also uses Element Reflection, is already shipping in Blink and WebKit.

Can you confirm whether the scope of this intent is element reflection only? Or does it include ElementInternals support as well?

(Coincidentally, I saw you filed this bug which seems to state that the ElementInternals support is currently not working.)

 

Blink component
Blink>DOM

TAG review
https://github.com/w3ctag/design-reviews/issues/134

TAG review status
Issues addressed

This tag review seems to be for AOM in general, as of its 2018 shape. I'm not sure there's been a lot of discussion as to where it ended up, with element reflection. Do you know of any TAG review or comments on the latest API?

However, I think this qualifies for an exception, under "already specified and accepted by the relevant standardization body", and "has already shipped in at least one other browser"

From what I understand, WPT allows some testing of accessibility tree mappings these days, via WebDriver hooks. For example:

• These tests appear to test the computed role
• These tests appear to test the computed accessible name

IIUC, the above test shows that content attributes (like <div role="region">) are reflected correctly in the accessibility tree. Would it be possible to add similar tests for the corresponding JavaScript code? Maybe that's not possible for most of the complex element relationships that this I2S is about, but I think you should be able to use element reflection to influence accessible name computation, at least? I don't think they need to be exhaustive, but just some tests to catch issues like the above-mentioned bug.

Flag name on chrome://flags
None

Finch feature name
None

Non-finch justification
None

I believe the recent guidance is that all new features should be guarded by a base::Feature flag, which then generates a Finch feature automatically.

 

Requires code in //chrome?
False

Tracking bug
https://crbug.com/981423

Measurement
Per-attribute UseCounters:
V8Element_AriaActiveDescendantElement_AttributeGetter
V8Element_AriaActiveDescendantElement_AttributeSetter
V8Element_AriaControlsElements_AttributeGetter
V8Element_AriaControlsElements_AttributeSetter (etc)

V8ElementInternals_AriaActiveDescendantElement_AttributeGetter
V8ElementInternals_AriaActiveDescendantElement_AttributeSetter
V8ElementInternals_AriaControlsElements_AttributeGetter
V8ElementInternals_AriaControlsElements_AttributeSetter (etc)

Estimated milestones
123 or 124

Anticipated spec changes
None

https://github.com/whatwg/html/pull/8496 contains a consolidated list of spec issues related to this area. The ones that seem relevant to this intent are https://github.com/whatwg/html/issues/8545 and https://github.com/whatwg/html/issues/8544. Can you tell us whether the spec changes that might come out of those issues, could have back-compat concerns?

Link to entry on the Chrome Platform Status
https://chromestatus.com/feature/6244885579431936

Links to previous Intent discussions
Ready for Trial:
https://groups.google.com/a/chromium.org/g/blink-dev/c/yecxBLmRVQI/m/d7YOe_nYAgAJ

[Daniel Bratell]

Hi from the future!

About Element Reflection, I'm curious if anyone is still working on this or if we should let go of this intent until some future time?

/Daniel

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CADsXd2Nixz41KJKXtd7TWQOrS%3DBWVOjSVKQJfqF_9OH6Cjqomg%40mail.gmail.com.

[alice]

Hi there,

Yes, I'm now (finally) working on this again :) Will send a longer
response once I have a more meaningful update to give.

Thanks

Alice

> [1].
>
> --
> You received this message because you are subscribed to a topic in the
> Google Groups "blink-dev" group.
> To unsubscribe from this topic, visit
> https://groups.google.com/a/chromium.org/d/topic/blink-dev/j8nZWueWc1s/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to

> blink-dev+...@chromium.org.
> To view this discussion on the web visit

> https://groups.google.com/a/chromium.org/d/msgid/blink-dev/a9ad1774-7794-4d93-a26d-21e618748016%40gmail.com
> [2].
>
>
> Links:
> ------
> [1] https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CADsXd2Nixz41KJKXtd7TWQOrS%3DBWVOjSVKQJfqF_9OH6Cjqomg%40mail.gmail.com?utm_medium=email&amp;utm_source=footer
> [2] https://groups.google.com/a/chromium.org/d/msgid/blink-dev/a9ad1774-7794-4d93-a26d-21e618748016%40gmail.com?utm_medium=email&utm_source=footer

[Daniel Bratell]

Good to hear!

/Daniel

[Alice Boxhall]

After many delays, I think this is finally ready for another look.

On Thursday, February 1, 2024 at 4:47:45 PM UTC+11 dom...@chromium.org wrote:

Very exciting to see this!

On Thu, Feb 1, 2024 at 12:10 AM alice <al...@igalia.com> wrote:

Contact emails
al...@igalia.com, mere...@chromium.org

Explainer
https://github.com/WICG/aom/blob/gh-pages/aria-reflection-explainer.md#reflecting-element-references

Specification
https://html.spec.whatwg.org/multipage/common-dom-interfaces.html#reflecting-content-attributes-in-idl-attributes:element
https://w3c.github.io/aria/#ARIAMixin

These specs are incompatible with each other, because https://github.com/w3c/aria/pull/1876 has not yet been merged. Do you think it'll be possible to get that merged soon?

This has now been merged.

 

Summary
This feature allows for ARIA relationship attributes to be reflected in
IDL as element references rather than DOMStrings.

Note: This intent specifically concerns the ARIA attributes using
Element Reflection, i.e. the attributes in the ARIAMixin interface with
a type of Element or FrozenArray<Element>. popoverTargetElement, which
also uses Element Reflection, is already shipping in Blink and WebKit.

Can you confirm whether the scope of this intent is element reflection only? Or does it include ElementInternals support as well?

(Coincidentally, I saw you filed this bug which seems to state that the ElementInternals support is currently not working.)

I had originally intended this to be only element reflection, but the AriaMixin properties on ElementInternals are now mapped through to accessibility APIs as well, so I think they should be in scope.

 

Blink component
Blink>DOM

TAG review
https://github.com/w3ctag/design-reviews/issues/134

TAG review status
Issues addressed

This tag review seems to be for AOM in general, as of its 2018 shape. I'm not sure there's been a lot of discussion as to where it ended up, with element reflection. Do you know of any TAG review or comments on the latest API?

I don’t know of any further TAG review specific to this API.

 

However, I think this qualifies for an exception, under "already specified and accepted by the relevant standardization body", and "has already shipped in at least one other browser"

Phew!

There is now a feature flag, “EnableAriaElementReflection”.

 

 

Requires code in //chrome?
False

Tracking bug
https://crbug.com/981423

Measurement
Per-attribute UseCounters:
V8Element_AriaActiveDescendantElement_AttributeGetter
V8Element_AriaActiveDescendantElement_AttributeSetter
V8Element_AriaControlsElements_AttributeGetter
V8Element_AriaControlsElements_AttributeSetter (etc)

V8ElementInternals_AriaActiveDescendantElement_AttributeGetter
V8ElementInternals_AriaActiveDescendantElement_AttributeSetter
V8ElementInternals_AriaControlsElements_AttributeGetter
V8ElementInternals_AriaControlsElements_AttributeSetter (etc)

Estimated milestones
123 or 124

Anticipated spec changes
None

https://github.com/whatwg/html/pull/8496 contains a consolidated list of spec issues related to this area. The ones that seem relevant to this intent are https://github.com/whatwg/html/issues/8545 and https://github.com/whatwg/html/issues/8544. Can you tell us whether the spec changes that might come out of those issues, could have back-compat concerns?

I think https://github.com/whatwg/html/issues/8545 has more or less been overtaken by events, given this API has been shipping in WebKit for some time. Given the only viable solution proposed was to change the API to use ObservableArray, this would obviously be a breaking change to a shipping API at this point.

I believe the WebKit implementation adopts Anne's proposal in https://github.com/whatwg/html/issues/8544 that elements referred to from ElementInternals don't need to be subject to the same Shadow DOM validation rules.

[Daniel Bratell]

LGTM1

/Daniel

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/bdb2a75c-5e7c-4475-b0a9-39870757ec62n%40chromium.org.

[Dan Clark]

Should this Intent be considered as including ariaOwnsElements? That was split off into a separate flag from the other properties here and it doesn't look like https://github.com/w3c/aria/issues/2266 has come to any definite conclusion yet.

I think the other properties are in a good state and I'm excited to see them ship. It would be great to clarify what the plan is for ariaOwnsElements as it's not yet clear to me that that one is ready.

-- Dan Clark

[Chris Harrelson]

Hi Alice,

Could you update the chromestatus entry's overview to explicitly list out all of the changes to web API IDLs, and any other details needed to understand what is proposed for shipping? I'm getting a bit confused about the status.

Thanks!

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/3a1e3c7f-9bbf-4d35-8184-60d4b6bb4606n%40chromium.org.

[alice]

On 2025-02-07 10:58, Chris Harrelson wrote:
> Hi Alice,
>

> Could you update the chromestatus entry [8]'s overview to explicitly

> list out all of the changes to web API IDLs, and any other details
> needed to understand what is proposed for shipping? I'm getting a bit
> confused about the status.

Definitely happy to update Chromestatus, but I'm a little lost as to
where in that entry these specifics should go.

I can answer your question (and Dan's) here, hopefully, in the meantime:

What is in scope are the ARIAMixin attributes
(https://w3c.github.io/aria/#ARIAMixin) with a type of `Element?` or
`FrozenArray<Element>?`, other than `ariaOwnsElements`, on both
`Element` and `ElementInternals`.

The relevant code for the IDL changes is all in
third_party/blink/renderer/core/dom/aria_relationship_attributes.idl,
which I can also paste below (other than the comment-only lines):

[
RuntimeEnabled=AOMAriaRelationshipProperties
] interface mixin AriaRelationshipAttributes {
[CEReactions, Reflect=aria_activedescendant, Measure] attribute
Element? ariaActiveDescendantElement;
[CEReactions, Measure] attribute FrozenArray<Element>?
ariaControlsElements;
[CEReactions, Measure] attribute FrozenArray<Element>?
ariaDescribedByElements;
[CEReactions, Measure] attribute FrozenArray<Element>?
ariaDetailsElements;
[CEReactions, Measure] attribute FrozenArray<Element>?
ariaErrorMessageElements;
[CEReactions, Measure] attribute FrozenArray<Element>?
ariaFlowToElements;
[CEReactions, Measure] attribute FrozenArray<Element>?
ariaLabelledByElements;
[CEReactions, Measure,
RuntimeEnabled=AOMAriaRelationshipPropertiesAriaOwns] attribute
FrozenArray<Element>? ariaOwnsElements;
};

Element includes AriaRelationshipAttributes;
ElementInternals includes AriaRelationshipAttributes;

> On Wed, Feb 5, 2025 at 7:03 PM 'Dan Clark' via blink-dev
> <blin...@chromium.org> wrote:
>

>> Should this Intent be considered as including ariaOwnsElements [1]?

>> That was split off into a separate flag from the other properties

>> here [2] and it doesn't look like

>> https://github.com/w3c/aria/issues/2266 has come to any definite
>> conclusion yet.
>>
>> I think the other properties are in a good state and I'm excited to
>> see them ship. It would be great to clarify what the plan is for
>> ariaOwnsElements as it's not yet clear to me that that one is ready.

To your question specifically: yes, I forgot to mention ariaOwnsElements
earlier so I appreciate the prompt! `ariaOwnsElements` does indeed need
more work, specifically around testing exhaustively enough that we can
be sure we haven't inadvertently introduced any new potential crash
conditions. I put `ariaOwnsElements` behind a separate flag after this
discussion with Aaron:
https://issues.chromium.org/issues/41469336#comment25

>> On Thursday, February 1, 2024 at 4:47:45 PM UTC+11
>> dom...@chromium.org wrote:

>> From what I understand, WPT allows some testing of accessibility
>> tree mappings these days, via WebDriver hooks. For example:
>>

>> * These tests appear to test the computed role [5]
>> * These tests appear to test the computed accessible name [6]

>>
>> IIUC, the above test shows that content attributes (like <div
>> role="region">) are reflected correctly in the accessibility tree.
>> Would it be possible to add similar tests for the corresponding
>> JavaScript code? Maybe that's not possible for most of the complex
>> element relationships that this I2S is about, but I think you should
>> be able to use element reflection to influence accessible name
>> computation, at least? I don't think they need to be exhaustive, but

>> just some tests to catch issues like the above-mentioned bug [3].

I forgot to answer this in my earlier email too, but I did add more WPT
tests covering the computed accessible name:

https://github.com/web-platform-tests/wpt/tree/master/html/dom/aria-element-reflection-labelledby.html
and
https://github.com/web-platform-tests/wpt/blob/master/custom-elements/element-internals-aria-element-reflection.html#L110

Thanks,

Alice

[Chris Harrelson]

On Thu, Feb 6, 2025 at 8:39 PM alice <al...@igalia.com> wrote:

On 2025-02-07 10:58, Chris Harrelson wrote:
> Hi Alice,
>
> Could you update the chromestatus entry [8]'s overview to explicitly
> list out all of the changes to web API IDLs, and any other details
> needed to understand what is proposed for shipping? I'm getting a bit
> confused about the status.

Definitely happy to update Chromestatus, but I'm a little lost as to
where in that entry these specifics should go.

I think the Overview section is a good place. This will make sure MDN documentation and other public communications are complete and accurate.

 

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/6f2caad673997591fb8a53b28314a535%40igalia.com.

[alice]

On 2025-02-08 05:06, Chris Harrelson wrote:
> On Thu, Feb 6, 2025 at 8:39 PM alice <al...@igalia.com> wrote:
>
>> On 2025-02-07 10:58, Chris Harrelson wrote:
>>> Hi Alice,
>>>
>>> Could you update the chromestatus entry [8]'s overview to
>> explicitly
>>> list out all of the changes to web API IDLs, and any other details
>>> needed to understand what is proposed for shipping? I'm getting a
>> bit
>>> confused about the status.
>>
>> Definitely happy to update Chromestatus, but I'm a little lost as to
>> where in that entry these specifics should go.
>
> I think the Overview section is a good place. This will make sure MDN
> documentation and other public communications are complete and
> accurate.

Thanks, I've updated the chromestatus entry.

[Chris Harrelson]

LGTM2

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/b86447fb06174a8889e1d3b5cae0e85b%40igalia.com.

[Mike Taylor]

LGTM3

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAOMQ%2Bw_iQbSjDaAuuMD2k8NNaPZU00ymmKuxo5QYetn_csFLBg%40mail.gmail.com.