ARIA IDL updates: enumerated attribute conversions, new "enumerated" wai-aria type, IDL examples #2484

rahimabdi · 2025-03-23T01:36:01Z

Closes #2281
Closes #2279

If helpful, I also created this tool to simulate how the new ARIA IDL works for enumerated attributes: https://rahimabdi.github.io/aria-idl-simulator/.

add enumerated attribute definitions for the following attributes including missing value default, invalid value default, keywords/states:
- aria-atomic
- aria-autocomplete
- aria-busy
- aria-checked
- aria-current
- aria-disabled
- aria-expanded
- aria-haspopup
- aria-hidden
- aria-invalid
- aria-live
- aria-modal
- aria-multiline
- aria-multiselectable
- aria-orientation
- aria-pressed
- aria-readonly
- aria-required
- aria-selected
- aria-sort
Revise "A. Mapping WAI-ARIA Value types to languages" to include enumerated attributes
Revise "6.2.4 Value" for permissible values (remove all other types except "enumerated"?)
Update "6.3 ARIA Attributes"
- Remove obsolete note in "6.3.4 ARIA nullable DOMString Attributes" about ARIA transitioning to non-nullable DOMString?
- Remote spec guidance around getting/setting to only apply to non-enumerated attributes
- Provide updated examples for "6.3.4.1 Example Attribute Usage"
Visual styling
- Remove <strong> style from old "defaults" values
- Confirm and apply style for new “State” column, state descriptions

Test, Documentation and Implementation tracking

Once this PR has been reviewed and has consensus from the working group, tests should be written and issues should be opened on browsers. Add N/A and check when not applicable.

"author MUST" tests:
"user agent MUST" tests:
Browser implementations (link to issue or commit):
- WebKit:
- Gecko:
- Blink:
Does this need AT implementations?
Related APG Issue/PR:
MDN Issue/PR:

Preview | Diff

netlify · 2025-03-23T01:36:19Z

✅ Deploy Preview for wai-aria ready!

Name	Link
🔨 Latest commit	`b2ba05c`
🔍 Latest deploy log	https://app.netlify.com/sites/wai-aria/deploys/680e623f1c81250008bd9810
😎 Deploy Preview	https://deploy-preview-2484--wai-aria.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

index.html

rahimabdi · 2025-03-23T02:19:28Z

index.html

                <td class="value-description">The element does not support being checked.</td>
              </tr>
            </tbody>
          </table>
+          <p>The attribute's <a data-cite="html/common-microsyntaxes.html#missing-value-default">missing value default</a> and <a data-cite="html/common-microsyntaxes.html#invalid-value-default">invalid value default</a> are both the Undefined state.</p>


Migrated comment from @keithamus (original):

I don't think we want the missing value default here to return the Undefined state, that will mean the .ariaChecked property will return "undefined" when aria-checked isn't on the element. I presume we want to return null instead? Browsers currently return null, so missing should be "no state", i.e. removed:

Suggested change

<p>The attribute's <a data-cite="html/common-microsyntaxes.html#missing-value-default">missing value default</a> and <a data-cite="html/common-microsyntaxes.html#invalid-value-default">invalid value default</a> are both the Undefined state.</p>

<p>The attribute has no <a data-cite="html/common-microsyntaxes.html#missing-value-default">missing value default</a> and its <a data-cite="html/common-microsyntaxes.html#invalid-value-default">invalid value default</a> is the Undefined state.</p>

index.html

rahimabdi · 2025-03-23T02:26:26Z

@keithamus:

@rahimabdi I've left a couple of review notes which I think apply in a lot of places, but rather than inundating you with review comments hopefully you can take the couple here and pattern match across the rest of the spec.

Thanks! I'll review those comments (which are migrated to this PR now) and respond.

rahimabdi · 2025-03-23T02:56:21Z

Re-added reviewers @pkra @spectranaut @cookiecrook @keithamus @scottaohara.

… rahim/update-aria-idl-2025

rahimabdi · 2025-04-27T17:08:13Z

CC @pkra @spectranaut @cookiecrook @keithamus @scottaohara @annevk

This PR is ready for review! I've made a number of updates, mainly:

Cleaned up enumerated attribute keywords/states per @keithamus's feedback
Changed aria-atomic's Missing state to Undefined, to align with other ARIA attributes that have an "Undefined" state
Added more IDL usage examples
Added a note clarifying that Undefined state is equivalent to "no state"

If helpful, I also created this tool to simulate how the new ARIA IDL works for enumerated attributes: https://rahimabdi.github.io/aria-idl-simulator/.

annevk

One thing that's nice in HTML is that all the states are a <dfn> and therefore also can be linked. But maybe that's best addressed in a follow-up.

annevk · 2025-04-28T06:54:55Z

index.html

+            Some ARIA attributes support an Undefined state, which is equivalent to having no state (i.e., null). User agent implementations may omit the Undefined state since the lack of an explicit
+            state results in the same behavior. For more information about determining the state of enumerated attributes, see


I think this sentence adds more confusion than it resolves. Especially since you cannot just leave it out at the moment without hitting an assert.

annevk · 2025-04-28T06:56:43Z

index.html

-            Default values from the ARIA values tables MUST NOT reflect to IDL as the <a data-cite="html/common-microsyntaxes.html#missing-value-default">missing value default</a> or the
-            <a data-cite="html/common-microsyntaxes.html#invalid-value-default">invalid value default</a> for the attribute. On getting, a missing ARIA attribute will return <code>null</code>. ARIA
-            attributes are not validated on get. If an ARIA value is invalid, on getting, it will return its set value as a literal string, and will not return an invalid value default.
+            For non-enumerated attributes, default values from the ARIA values tables MUST NOT reflect to IDL as the


This seems okay to state as a note, but it shouldn't be a requirement. HTML already requires this.

pkra · 2025-05-08T17:32:57Z

index.html

@@ -12761,7 +12802,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
              </tr>
              <tr>
                <th class="state-value-head" scope="row">Value:</th>
-                <td class="state-value"><a href="#valuetype_tristate">tristate</a></td>
+                <a href="#valuetype_enumerated">enumerated</a>


This seems better

Suggested change

<a href="#valuetype_enumerated">enumerated</a>

<td class="state-value"><a href="#valuetype_enumerated">enumerated</a></td>

cyns · 2025-05-08T17:35:11Z

@aleventhal you may want to review this

pkra · 2025-05-08T17:44:16Z

index.html

                <td class="value-description">
                  When a user is providing input, an element containing a collection of values that could complete the provided input might be displayed. If displayed, one value in the collection is
                  automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input.
                </td>
              </tr>
              <tr>
-                <th class="value-name" scope="row"><strong class="default">none (default)</strong></th>
+                <th class="value-name" scope="row">none</th>


Is it intentional that (default) is dropped here? (And in 18 other instances.)

spectranaut · 2025-05-08T18:14:24Z

Discussed in today's meeting: https://www.w3.org/2025/05/08-aria-minutes.html#7d9a

cyns

lgtm! this is much more clear, thank you

index.html

keithamus · 2025-05-12T08:46:44Z

index.html

+          <p>
+            For <a data-cite="html/common-dom-interfaces.html#reflect">reflection</a> purposes, the attribute's
+            <a data-cite="html/common-microsyntaxes.html#missing-value-default">missing value default</a> is the Undefined state (null) that has no associated keyword, and its
+            <a data-cite="html/common-microsyntaxes.html#invalid-value-default">invalid value default</a> is the False state.


(Blocking) So I believe this kind of change to the spec is web observable, which means it will need changes to the implementations and we need to ensure compatibility for web developers who may depend on the existing behaviour. Unless I am missing that somewhere we clarify that reflected enumerated properties should only return the value of the content attribute?

In this example the web observable piece is that the "invalid value default" is the False state, which means that any invalid value would map to the False (for which I presume the keyword is "false" - see above).

This means pasting this HTML into your URL bar:

data:text/html,<body id=b><div id=d aria-atomic=foo><script>b.append(d.ariaAtomic)</script>

Should render false on the page. But right now it renders foo.

I think this will be the same for all of these properties, e.g. aria-autocomplete, aria-checked and so on.

Right, we should have tests for this and such, but this is very much the motivation for making this change. This makes these IDL attributes more meaningful and enables them to be used for feature testing going forward.

For sure, I appreciate the motivation for it, I just want us to be cautious about introducing changes to the spec without getting tests & approval from the various engines.

keithamus · 2025-05-12T08:53:48Z

index.html

                <td class="value-description">The element is checked.</td>
              </tr>
              <tr>
-                <th class="value-name" scope="row"><strong class="default">undefined</strong> (default)</th>
+                <th class="value-name" scope="row">undefined, empty string ("")</th>


(Non-blocking) We could reasonably drop the undefined keyword here:

Suggested change

<th class="value-name" scope="row">undefined, empty string ("")</th>

<th class="value-name" scope="row">empty string ("")</th>

If someone set "undefined" then it would map to the invalid value default, which is the undefined state. The only reason not to do this is if you want the canonicalization steps to explicitly return undefined rather than the empty string.

The same is true for other properties, e.g. aria-current, and so on.

Rahim Abdi added 7 commits March 22, 2025 15:43

Remove old value type definitions, add enumerated type definition

9cf8f17

Update more IDL-related sections, IDL examples section

3f322c6

Add aria-atomic, aria-autocomplete

ae9958c

Add more attributes

dcb2fc8

Add more enumerated attributes

ab972a3

More updates

f0f9cb4

More attributes added, updated wai-aria values schema table

16391bc

github-actions bot added the spec:aria label Mar 23, 2025

Clean up

d67d5d9

rahimabdi mentioned this pull request Mar 23, 2025

ARIA IDL updates: convert eligible attributes to enumerated, new ARIA IDL guidance and examples #2413

Closed

10 tasks

rahimabdi commented Mar 23, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

rahimabdi commented Mar 23, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

rahimabdi requested review from cookiecrook, keithamus, pkra, spectranaut and scottaohara March 23, 2025 02:55

rahimabdi marked this pull request as draft March 27, 2025 17:23

Rahim Abdi and others added 8 commits April 27, 2025 08:03

Updates to 'ARIA Attributes' section

35a50fd

chore: prettier

487fa34

enumerated attribute cleanup

b272af5

Fix merge conflicts

21f843f

More cleanup

a202cab

chore: prettier

172d4de

Typo fix for 'Value' section

b257b1c

Merge branch 'rahim/update-aria-idl-2025' of github.com:w3c/aria into…

72a131a

… rahim/update-aria-idl-2025

Rahim Abdi and others added 2 commits April 27, 2025 09:58

Clarify no-state behavior

97e7145

chore: prettier

b2ba05c

rahimabdi removed request for cookiecrook, keithamus, pkra, spectranaut and scottaohara April 27, 2025 17:02

rahimabdi marked this pull request as ready for review April 27, 2025 17:03

rahimabdi requested review from keithamus, annevk, cookiecrook, pkra, spectranaut and scottaohara and removed request for annevk April 27, 2025 17:08

rahimabdi added the Agenda label Apr 27, 2025

annevk reviewed Apr 28, 2025

View reviewed changes

pkra reviewed May 8, 2025

View reviewed changes

cyns self-requested a review May 8, 2025 17:40

pkra reviewed May 8, 2025

View reviewed changes

cyns approved these changes May 8, 2025

View reviewed changes

keithamus requested changes May 12, 2025

View reviewed changes

spectranaut removed the Agenda label May 20, 2025

spectranaut moved this to All PRS in ARIA Normative PR Tracking Jun 13, 2025

spectranaut added this to ARIA Normative PR Tracking Jun 13, 2025

spectranaut moved this from All PRS to Needs Consensus/Review in ARIA Normative PR Tracking Jun 13, 2025

	<p>The attribute's <a data-cite="html/common-microsyntaxes.html#missing-value-default">missing value default</a> and <a data-cite="html/common-microsyntaxes.html#invalid-value-default">invalid value default</a> are both the Undefined state.</p>
	<p>The attribute has no <a data-cite="html/common-microsyntaxes.html#missing-value-default">missing value default</a> and its <a data-cite="html/common-microsyntaxes.html#invalid-value-default">invalid value default</a> is the Undefined state.</p>

		Some ARIA attributes support an Undefined state, which is equivalent to having no state (i.e., null). User agent implementations may omit the Undefined state since the lack of an explicit
		state results in the same behavior. For more information about determining the state of enumerated attributes, see

	<a href="#valuetype_enumerated">enumerated</a>
	<td class="state-value"><a href="#valuetype_enumerated">enumerated</a></td>

	<th class="value-name" scope="row">undefined, empty string ("")</th>
	<th class="value-name" scope="row">empty string ("")</th>

ARIA IDL updates: enumerated attribute conversions, new "enumerated" wai-aria type, IDL examples #2484

Are you sure you want to change the base?

ARIA IDL updates: enumerated attribute conversions, new "enumerated" wai-aria type, IDL examples #2484

Uh oh!

Conversation

rahimabdi commented Mar 23, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test, Documentation and Implementation tracking

Uh oh!

netlify bot commented Mar 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for wai-aria ready!

Uh oh!

Uh oh!

rahimabdi Mar 23, 2025 • edited by keithamus Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rahimabdi commented Mar 23, 2025

Uh oh!

rahimabdi commented Mar 23, 2025

Uh oh!

rahimabdi commented Apr 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

annevk left a comment

Choose a reason for hiding this comment

Uh oh!

annevk Apr 28, 2025

Choose a reason for hiding this comment

Uh oh!

annevk Apr 28, 2025

Choose a reason for hiding this comment

Uh oh!

pkra May 8, 2025

Choose a reason for hiding this comment

Uh oh!

cyns commented May 8, 2025

Uh oh!

pkra May 8, 2025

Choose a reason for hiding this comment

Uh oh!

spectranaut commented May 8, 2025

Uh oh!

cyns left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

keithamus May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

annevk May 14, 2025

Choose a reason for hiding this comment

Uh oh!

keithamus May 14, 2025

Choose a reason for hiding this comment

Uh oh!

keithamus May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rahimabdi commented Mar 23, 2025 •

edited by pr-preview bot

Loading

netlify bot commented Mar 23, 2025 •

edited

Loading

rahimabdi Mar 23, 2025 •

edited by keithamus

Loading

rahimabdi commented Apr 27, 2025 •

edited

Loading

keithamus May 12, 2025 •

edited

Loading

keithamus May 12, 2025 •

edited

Loading