Allow setting default accessibility semantics for custom elements #4658

domenic · 2019-05-23T18:32:09Z

This WIP pull request drafts a mechanism for using ElementInternals to set a custom element's default accessible role, states, and properties. It builds on w3c/aria#984 and must not be merged before that dependency is ready.

Perhaps a separate issue, but one this PR makes more apparent: I think we should add some text in the custom elements section generally that encourages custom element authors to have a more formalized contract with their consumers, e.g. provide their own recommended content model, strong native accessibility semantics, etc. I touched on this briefly in the example but it should probably be somewhere more normative as well.

Things I could use reviewer feedback on (now resolved):

Naming. I sometimes used "default" and sometimes "native". I'm not sure what's more correct. Similarly between "accessibility", "ARIA", and "WAI-ARIA", I tried to use what felt more natural, but might have got it wrong. Sometimes I used "semantics" to mean "roles, states, or properties"; is that good?
Placement of spec text. I put the ElementInternals stuff in ElementInternals, but then how that impacts the processing model for AT I put in the "Requirements related to ARIA and to platform accessibility APIs" section. And then I put an example in our intro-to-custom-elements example section. This feels a bit spread out; is it OK?
Processing model. I tried to clarify in https://github.com/w3c/aria/issues/982 what the best way to insert the custom elements default values into the "ARIA cascade" was, and this was the best I could come up with. But maybe there is something better or more precise.

/cc @tkent-google @alice @stevefaulkner (your help as HTML-AAM editor would be especially appreciated) @whatwg/a11y @whatwg/components. I'm also happy to open an issue on w3c/webcomponents if folks think that would be helpful.

At least two implementers are interested (and none opposed):
- Blink
- Gecko says worth prototyping
- WebKit says pretty reasonable
Tests are written and can be reviewed and commented upon at:
- Add ARIA role, state and properties to ElementInternals web-platform-tests/wpt#18223
Implementation bugs are filed:
- Chrome: https://bugs.chromium.org/p/chromium/issues/detail?id=991165
- Firefox: https://bugzilla.mozilla.org/show_bug.cgi?id=1665151
- Safari: https://bugs.webkit.org/show_bug.cgi?id=216570

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

/custom-elements.html ( diff )
/dom.html ( diff )
/index.html ( diff )
/infrastructure.html ( diff )

rniwa · 2019-05-23T20:24:30Z

One thing that's strange about this approach is that ARIA roles are typically an intrinsic property of an element, not something that change over time. There is input element but that's more of an anomaly than not. I think it makes more sense to have this be an optional argument to customElements.define instead.

domenic · 2019-05-23T20:28:29Z

Well, there's actually a lot of cases where things change. You can see https://w3c.github.io/html-aam/#html-element-role-mappings for details. The others are:

<a> and <area> (changes based on href attribute)
<datalist> (whether or not it's connected to an <input>)
<footer> and <header> (depending on their parent)
<form> (depending on whether or not it has an accessible name)
<img> (depending on its alt="" attribute)
<li> (depending on its parent)

... well, you get the idea; I stopped at "L". Most complex controls, or controls that have relationships with other controls, need the ability to dynamically change their role.

jnurthen · 2019-05-23T21:32:51Z

I don't know if this influences this decision but the ARIA spec states the following at http://w3c.github.io/aria/#roles

Roles are element types and authors MUST NOT change role values over time or with user actions. Authors wishing to change a role MUST do so by deleting the associated element and its children and replacing it with a new element with the appropriate role. Typically, platform accessibility APIs do not provide a vehicle to notify assistive technologies of a role value change, and consequently, assistive technologies may not update their cache with the new role attribute value.

domenic · 2019-05-23T21:37:18Z

Hmm, thanks @jnurthen, that is interesting. The first half of the paragraph, about author behavior, is not as relevant. But the part about platform accessibility APIs not being able to adapt to role changes is quite relevant.

Can someone who works on browser AT confirm that if I write

<a>placeholder</a>
<script>
document.querySelector('a').href = 'https://example.com/';
</script>

then AT users will forever see the <a> as having no role (e.g. UIA Text), instead of the link role (e.g. UIA HyperLink)?

If that's the case, then I guess custom elements aren't going to be able to do any better, and we do need to re-think the design away from a mutable property.

stevefaulkner · 2019-05-23T21:54:32Z

@domenic that's not the best example as despite what the AAM currently says seems like browsers expose the link role regardless of presence of href, bug filed w3c/html-aam#196 :-)

have created a modded test case which tests, i think, what you were asking. no issue for AT.

domenic · 2019-05-23T21:59:03Z

Ah, thank you! Well, perhaps I should just start testing those cases I listed myself, but do you know off the top of your head the answer for their analogues? E.g.

<body>
<main></main>
<footer>I have contentinfo role to start with</footer>
<script>
document.querySelector("main").append(document.querySelector("footer"));
// now it should have no role
</script>
</body>

or

<img src="test" alt=""> <!-- presentation role to start with -->
<script>
document.querySelector('img').alt = 'a test image';
// now it should have img role
</script>

?

jnurthen · 2019-05-23T22:14:17Z

have created a modded test case which tests, i think, what you were asking. no issue for AT.

@stevefaulkner I'm interested to know how you tested this? Are you looking at the internal browser representation of the tree, the Platform accessibility APIs or what is actually being presented to the user using (for example) a screen reader.
I think the first 2 would be expected to work - where there is a question is whether the screen reader has its own cached copy - I don't know enough about screen reader internals to know if this is still the case or not.

annevk · 2019-05-24T08:06:25Z

If more investigation is required here, perhaps an issue can be used? That'll make reviewing the eventual text a little easier.

stevefaulkner · 2019-05-24T09:31:50Z

@jnurthen

I'm interested to know how you tested this?

I looked at acc API info, browser acc tree and navigated with JAWS and NVDA.

I also created a second test case with a button to trigger the type change. Same result - SR's tested had no problem with the type change.

LJWatson · 2019-05-24T13:01:48Z

@domenic commented:

Naming. I sometimes used "default" and sometimes "native". I'm not sure what's more correct. Similarly between "accessibility", "ARIA", and "WAI-ARIA",
I tried to use what felt more natural, but might have got it wrong. Sometimes I used "semantics" to mean "roles, states, or properties"; is that good?>

The terms "default" and "native" are both correct and interchangeable in this context.

One consideration is that neither "default" nor "native" has an elegant counterpart that describes its opposite. Using "implicit" and "explicit" is one way to make the two different concepts clear, though arguably those terms are harder to comprehend.

The ARIA spec seems to use "default", "native", "implicit", and also "Host language semantics" without particular preference.

Is it worth adding a definition of whichever terms are used, that explains the common alternative terms that are used interchangeably with them?

Most people refer to "ARIA", but AIRC the official "WAI-ARIA" name was necessary because "ARIA" was already trademarked elsewhere. If it's possible to use "ARIA" in the prose but reference "WAI-ARIA" in the biblio, that would be the best of both worlds, if not I think it'll have to be the more awkward formal name.

Using "semantics" or "accessibility semantics" if you want to put particular emphasis on it, to mean role, state and property information, is absolutely fine.

jnurthen · 2019-05-24T15:54:13Z

@jnurthen

I'm interested to know how you tested this?

I looked at acc API info, browser acc tree and navigated with JAWS and NVDA.

I also created a second test case with a button to trigger the type change. Same result - SR's tested had no problem with the type change.

My brief testing showed the same but before moving forward with assuming this text in the ARIA spec is now obsolete I'd like to get the opinion of developers of JAWS, NVDA, ORCA, VO (and others if we can find them). I've opened w3c/aria#986 to ask the question if the ARIA spec text is still accurate.

caridy · 2019-05-24T17:53:51Z

There is input element but that's more of an anomaly than not. I think it makes more sense to have this be an optional argument to customElements.define instead.

@rniwa, this option has surfaced multiple times... we are not Ok with forcing the author of the component to register the component, that doesn't work for us, and does not work for many other folks that produce components that can be registered by their consumers with arbitrary tag names.

rniwa · 2019-05-24T22:42:19Z

There is input element but that's more of an anomaly than not. I think it makes more sense to have this be an optional argument to customElements.define instead.

@rniwa, this option has surfaced multiple times... we are not Ok with forcing the author of the component to register the component, that doesn't work for us, and does not work for many other folks that produce components that can be registered by their consumers with arbitrary tag names.

That's an orthogonal issue. Custom element class can easily define a static method for ARIA role and whoever defines a concrete custom element could use that ARIA role via static method.

tkent-google · 2019-06-11T07:50:48Z

source

+    this._checked = false;
+    this.addEventListener('click', this._onClick.bind(this));
+
+<mark>    this._internals.role = "checkbox";


nit: In this code example, single quotes are used.

tkent-google · 2019-06-11T07:52:38Z

source

+
+  <div w-nodev>
+
+  <p>Each <span>custom element</span> has a <dfn>native accessibility semantics map</dfn>, which is


Maybe we should mention the initial content of native accessibility semantics map. It's empty initially?

domenic · 2019-06-14T19:01:22Z

@rniwa given the above input from accessibility folks about how native elements often experience role changes, do you think the API here is reasonable to allow custom element authors to achieve the same thing? We could also open an issue with that precise question on the ARIA repository to get more input.

alice · 2019-06-17T00:12:21Z

TL;DR - I think having a way to set a default role on a custom element would be nice, but we absolutely shouldn't exclude it from ElementInternals.

I do see role as typically an intrinsic, static property of an element, but in practice it does change if some property causes the element to be displayed in a different enough way that it is using a different UI metaphor altogether. Another example, beyond input, is <select>, which has totally different appearance and thus role depending on the values of multiple and/or size.

You could argue that custom elements which have a visual appearance should always map to a single UI metaphor, but that seems overly restrictive to me.

Also, given you can change element.role, I would expect authors would have some frustration and confusion at not having a parallel API for ElementInternals.

In Blink, we have code to handle a role changing by destroying and re-creating the associated accessibility node, effectively doing what the ARIA advice suggests authors do themselves. WebKit also has code to handle a role change.

It might be nice to have a way to set a default value for the value of role on ElementInternals via the custom element definition process[1]. However, I don't think we have much to gain by having that be the only way to set role.

--

[1] Perhaps that could also do something clever with other required ARIA attributes associated with that role? Though in practice, ARIA takes care of that by specifying default values where the attribute is not set.

Adds a way to set default ARIA role, state & properties for custom elements through ElementInternals. These can be overridden with setting the ARIA attributes on the element directly. See whatwg/html#4658 for spec PR. Change-Id: I0caf6bc302445e48f4e0324513105eba3d6303a6

annevk · 2019-09-25T09:59:32Z

I find it a bit confusing that the definition of the attributes defined at https://w3c.github.io/aria/#dom-ariaattributes use "reflect" whereas here we use a different definition. It seems there should be some kind of abstraction that allows the object that includes the mixin to decide how they work and then the "reflect" definition can be used for elements (maybe, see w3c/aria#1058) and this definition can be used for internals.

domenic · 2019-09-25T10:01:12Z

That's actually exactly what it does :). See the linked ARIA PR which sets up that infrastructure.

…lementInternals, a=testonly Automatic update from web-platform-tests Add ARIA role, state and properties to ElementInternals Adds a way to set default ARIA role, state & properties for custom elements through ElementInternals. These can be overridden with setting the ARIA attributes on the element directly. See whatwg/html#4658 for spec PR. Explainer: https://github.com/alice/aom/blob/gh-pages/explainer.md#per-instance-dynamic-semantics-via-the-elementinternals-object Intent to Implement: https://groups.google.com/a/chromium.org/d/msg/blink-dev/b-cGz9c67pM/0zvBzjhrAAAJ Change-Id: I0caf6bc302445e48f4e0324513105eba3d6303a6 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1709950 Commit-Queue: Rakina Zata Amni <rakinachromium.org> Reviewed-by: Alice Boxhall <aboxhallchromium.org> Reviewed-by: Kent Tamura <tkentchromium.org> Cr-Commit-Position: refs/heads/master{#685141} -- wpt-commits: 5c61f2493fe744dc9f3d08e1f5a80165f574cfa3 wpt-pr: 18223 UltraBlame original commit: a95eec38bb25d830da2c2414356d5904c8e99d6d

sketching ElementInternals Form-associated elements are now working. Remaining test failures in custom-elements/form-associated/ are: * whatwg/html#4658 hasn't made it into the standard yet, and ElementInternals-accessibility is all about that functionality. * ElementInternals-setFormValue hits many race conditions with our iframe order of operations. Isolating just the "submit this form with these custom elements, look at the query" part, the payload of each test actually does pass! Running the tests as written, we end up with different tests overwriting each other's elements and getting very confused. One problem is the about:blank double-load-event thing, but fixing that doesn't fix everything. * ElementInternals-validation doesn't work because we don't have form validation in general; I've commented the relevant stubs. * ElementInternals-form-disabled-callback fails on #25713.

hober · 2020-03-11T17:53:56Z

Note that Mozilla considers this worth prototyping: mozilla/standards-positions#201

rniwa · 2020-08-28T17:02:51Z

@rniwa given the above input from accessibility folks about how native elements often experience role changes, do you think the API here is reasonable to allow custom element authors to achieve the same thing? We could also open an issue with that precise question on the ARIA repository to get more input.

Sorry for the delay. I had been out on a medical leave for 4 months. We had some extensive internal discussions about this, and we now believe this is a pretty reasonable API. We'd like to see some sugar for defining the default role for a class of custom elements (e.g. maybe a static variable on class) but that could be tackled separately.

domenic · 2020-08-28T19:41:53Z

Awesome, thank you @rniwa! I've rebased this on master. It's still blocked on w3c/aria#984, but otherwise it should be ready to merge; any review is appreciated.

source

annevk · 2020-09-07T14:10:33Z

cc @whatwg/a11y @whatwg/components (unclear if the OP notification worked as the bot that modifies OP isn't able to ping these groups)

annevk

Found two possible nits and pushed a fixup for the remainder.

source

domenic added addition/proposal New features or enhancements do not merge yet Pull request must not be merged per rationale in comment accessibility Affects accessibility topic: custom elements Relates to custom elements (as defined in DOM and HTML) labels May 23, 2019

caridy mentioned this pull request May 23, 2019

[alignment with standards] refactor AOM properties to be surfaced via ElementInternals salesforce/lwc#717

Closed

jnurthen mentioned this pull request May 24, 2019

Is the text that prohibits changing roles obsolete? w3c/aria#986

Closed

domenic mentioned this pull request Jun 5, 2019

Discuss how to customize appearance tkent-google/std-switch#7

Closed

tkent-google reviewed Jun 11, 2019

View reviewed changes

domenic force-pushed the domenic/elementinternals-a11y branch from 6347136 to f138256 Compare June 14, 2019 18:59

domenic mentioned this pull request Jun 14, 2019

Generalize AccessibilityRole/AriaAttributes IDL w3c/aria#984

Merged

chromium-wpt-export-bot mentioned this pull request Aug 1, 2019

Add ARIA role, state and properties to ElementInternals web-platform-tests/wpt#18223

Merged

rakina mentioned this pull request Aug 7, 2019

Default accessibility semantics for custom elements w3ctag/design-reviews#401

Closed

3 tasks

scottaohara mentioned this pull request Oct 4, 2019

update custom element w3c/html-aria#180

Closed

tkent-google mentioned this pull request Dec 18, 2019

ElementInternals should work with customized built-in elements #5166

Open

pshaughn mentioned this pull request Feb 8, 2020

form-associated custom elements and their ElementInternals servo/servo#25705

Closed

rniwa mentioned this pull request Mar 25, 2020

2020 Virtual F2F for Accessibility and Web Components WICG/webcomponents#872

Closed

domenic force-pushed the domenic/elementinternals-a11y branch from e32a070 to e95cc26 Compare August 28, 2020 19:41

domenic requested a review from annevk August 28, 2020 19:42

annevk reviewed Aug 31, 2020

View reviewed changes

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Show resolved Hide resolved

source Show resolved Hide resolved

source Show resolved Hide resolved

annevk approved these changes Sep 7, 2020

View reviewed changes

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

domenic and others added 5 commits September 15, 2020 13:19

Allow setting default accessibility semantics for custom elements

10998ca

Code review comments

5b35ca9

Fix names and use passed in variable

9ce8c91

No need for otherwise

122cda1

More links

2eb1db1

domenic force-pushed the domenic/elementinternals-a11y branch from 1fba51f to 2eb1db1 Compare September 15, 2020 17:34

domenic merged commit f7a3dcc into master Sep 18, 2020

domenic deleted the domenic/elementinternals-a11y branch September 18, 2020 17:35

mtrootyy mentioned this pull request Sep 18, 2020

updates to custom elements w3c/html-aria#210

Merged

Westbrook mentioned this pull request Jan 8, 2021

Support for AOM implementation at the browser level with polyfill and documentation of current capabilities w3c/webcomponents-cg#3

Open

cathiechen mentioned this pull request Apr 2, 2024

Implement form-associated custom elements and their ElementInternals servo/servo#31980

Merged

4 tasks

servo-wpt-sync mentioned this pull request Apr 2, 2024

Implement form-associated custom elements and their ElementInternals web-platform-tests/wpt#45471

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow setting default accessibility semantics for custom elements #4658

Allow setting default accessibility semantics for custom elements #4658

domenic commented May 23, 2019 •

edited by pr-preview bot

Loading

rniwa commented May 23, 2019

domenic commented May 23, 2019

jnurthen commented May 23, 2019

domenic commented May 23, 2019

stevefaulkner commented May 23, 2019 •

edited

Loading

domenic commented May 23, 2019

jnurthen commented May 23, 2019 •

edited

Loading

annevk commented May 24, 2019

stevefaulkner commented May 24, 2019

LJWatson commented May 24, 2019

jnurthen commented May 24, 2019

caridy commented May 24, 2019

rniwa commented May 24, 2019

tkent-google Jun 11, 2019

tkent-google Jun 11, 2019

domenic commented Jun 14, 2019

alice commented Jun 17, 2019

annevk commented Sep 25, 2019

domenic commented Sep 25, 2019

hober commented Mar 11, 2020

rniwa commented Aug 28, 2020

domenic commented Aug 28, 2020

annevk commented Sep 7, 2020

annevk left a comment


		<div w-nodev>

		<p>Each <span>custom element</span> has a <dfn>native accessibility semantics map</dfn>, which is

Allow setting default accessibility semantics for custom elements #4658

Allow setting default accessibility semantics for custom elements #4658

Conversation

domenic commented May 23, 2019 • edited by pr-preview bot Loading

rniwa commented May 23, 2019

domenic commented May 23, 2019

jnurthen commented May 23, 2019

domenic commented May 23, 2019

stevefaulkner commented May 23, 2019 • edited Loading

domenic commented May 23, 2019

jnurthen commented May 23, 2019 • edited Loading

annevk commented May 24, 2019

stevefaulkner commented May 24, 2019

LJWatson commented May 24, 2019

jnurthen commented May 24, 2019

caridy commented May 24, 2019

rniwa commented May 24, 2019

tkent-google Jun 11, 2019

Choose a reason for hiding this comment

tkent-google Jun 11, 2019

Choose a reason for hiding this comment

domenic commented Jun 14, 2019

alice commented Jun 17, 2019

annevk commented Sep 25, 2019

domenic commented Sep 25, 2019

hober commented Mar 11, 2020

rniwa commented Aug 28, 2020

domenic commented Aug 28, 2020

annevk commented Sep 7, 2020

annevk left a comment

Choose a reason for hiding this comment

domenic commented May 23, 2019 •

edited by pr-preview bot

Loading

stevefaulkner commented May 23, 2019 •

edited

Loading

jnurthen commented May 23, 2019 •

edited

Loading