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

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

Closes #2281
Closes #2279

Mini-Explainer

Summary of Changes

Convert following ARIA attributes to enumerated:
- 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 "Mapping WAI-ARIA Value types to languages" to include enumerated attributes
Revise "6.2.4 Value" value types
Update "6.3 ARIA Attributes" section
Remove obsolete note in "6.3.4 ARIA nullable DOMString Attributes" about ARIA transitioning to non-nullable DOMString?
Update ARIA IDL usage examples in "6.3.4.1 Example Attribute Usage"
Add note clarifying "Undefined" state vs. "undefined" string assignment

Feature Flag Testing in Safari Tech Preview

You can test the new ARIA IDL reflection behavior with a feature flag in Safari Tech Preview 228. Ensure that "Show features for developers" is enabled (Settings -> Advanced), and then enable the "Enumerated ARIA Attribute Reflection" flag (Settings -> Feature Flags, "JavaScript" section).

The following page can help with quick IDL testing: https://2553411.playcode.io.

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.

Meeting Notes

ARIA WG & Salesforce Sync (Sept 30 2025)

Presentation deck
- Salesforce/ARIA WG IDL sync (Google Slides)
Attendees
- @keithamus, @cookiecrook, @rahimabdi, @gregwhitworth (and other Salesforce team members: Caridy, Eva, Mai, Jason)
On the LWC side (Lightning Web Components), no anticipated impact unless testing reveals issues
For first-party code, Salesforce framework doesn’t do significant normalization; primary areas of concern would be new behavior around null/undefined/default values
The Salesforce ARIA IDL polyfill is currently being removed, and it’s only there for backwards compatibility
There may be potential impact for code packages that aren’t being maintained. For customer code, need a way to communicate the changes (anticipating low impact); Salesforce to investigate an opt-in fallback behavior for those relying on old behavior
Next steps
- Salesforce folks to regroup with the ARIA WG in mid-October after completion of impact analysis to LWC and Salesforce first-party code
- Ideal to wait for Chrome/Firefox to ship the ARIA IDL changes behind a flag as well, and to maintain the flag so it can be toggled off if needed. The goal is to ensure webcompat, so the ARIA WG does not wish to rush the change

Preview | Diff

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

✅ Deploy Preview for wai-aria ready!

Name	Link
🔨 Latest commit	`5dc7486`
🔍 Latest deploy log	https://app.netlify.com/projects/wai-aria/deploys/68cf37fe7749bc000911808b
😎 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 project configuration.

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.

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.

Part of this could be an informative note for authors/implementors, rather than in the normative text of the Enumerated Attribute definition.

Do we ever anticipate a time where the explicit "undefined" content attribute values would need to map to an Undefined state, separately than the Null state? For example, I think the only scenarios where an undefined is allowed are with the undefined/true/false/[/mixed] enumerated values, but since the Missing Default and Invalid Default are the same one those, there is no impact... Can we foresee any scenario where those would be different? For example, if undefined was an allowed token value of aria-invalid? (Presumably we just need to always avoid that, which seems okay.)

See @keithamus' related comment in https://github.com/w3c/aria/pull/2484/files#r2084175913

@annevk @cookiecrook Got it, I've removed this sentence: "User agent implementations may omit the Undefined state since the lack of an explicit state results in the same behavior."

@keithamus Hopefully the link to the HTML spec (which defines the state computation algorithm) is sufficient.

Do we ever anticipate a time where the explicit "undefined" content attribute values would need to map to an Undefined state, separately than the Null state? For example, I think the only scenarios where an undefined is allowed are with the undefined/true/false/[/mixed] enumerated values, but since the Missing Default and Invalid Default are the same one those, there is no impact... Can we foresee any scenario where those would be different? For example, if undefined was an allowed token value of aria-invalid? (Presumably we just need to always avoid that, which seems okay.)

As @keithamus also mentioned, the "undefined" content attribute value will map to the invalid value default (effectively treated as invalid), and fortunately there's no need for any ARIA attribute to have an explicit "undefined" keyword (nor an Undefined state mapping to "undefined" the keyword). I plan to add a note on this in this PR.

Here are all the attributes which currently support a value of "undefined" per spec, all mapping to their respective invalid value defaults and equivalent with behavior currently defined in spec:

aria-checked ("undefined" maps to null)

aria-expanded ("undefined" maps to null)

aria-hidden ("undefined" maps to False state)

aria-orientation ("undefined" maps to null)

aria-pressed ("undefined" maps to null)

aria-selected ("undefined" maps to null)

Note: Each of these 6 attributes also supports the empty string as a keyword, so "" and "undefined" are the same.

Only two enumerated ARIA attributes have differing invalid/missing value defaults and they don't support "undefined" however, any invalid value provided to them should result in a value of "true" per spec (now that they're enumerated, this is handled by the invalid value default):

aria-current

invalid value default = True state

missing value default = False state

aria-invalid

invalid value default = True state

missing value default = False state

index.html

https://bugs.webkit.org/show_bug.cgi?id=296851 rdar://157952768 Reviewed by NOBODY (OOPS!). Adds 'status: developer' feature flag for enumerated ARIA attributes: w3c/aria#2484. The ARIA spec intends to convert the following attributes to be enumerated, i.e., content attributes with permissible keywords and invalid/missing value defaults: - 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 This PR changes ARIA's IDL to use [ReflectSetter] for enumerated attributes in order to implement the desired reflection behavior behind a flag using manual getters; this also allows maintaining current ARIA IDL behavior when the flag is disabled. When ARIA PR WebKit#2484 lands, ARIA's IDL should be updated to use [Reflect, Enumerated] for automatic JS bindings codegen that doesn't need manual code. * Source/WTF/Scripts/Preferences/UnifiedWebPreferences.yaml: * Source/WebCore/accessibility/AriaAttributes.idl: * Source/WebCore/dom/Element.h: * Source/WebCore/dom/Element.cpp: (WebCore::Element::ariaAtomic const): (WebCore::Element::ariaAutoComplete const): (WebCore::Element::ariaBusy const): (WebCore::Element::ariaChecked const): (WebCore::Element::ariaCurrent const): (WebCore::Element::ariaDisabled const): (WebCore::Element::ariaExpanded const): (WebCore::Element::ariaHasPopup const): (WebCore::Element::ariaHidden const): (WebCore::Element::ariaInvalid const): (WebCore::Element::ariaLive const): (WebCore::Element::ariaModal const): (WebCore::Element::ariaMultiLine const): (WebCore::Element::ariaMultiSelectable const): (WebCore::Element::ariaOrientation const): (WebCore::Element::ariaPressed const): (WebCore::Element::ariaReadOnly const): (WebCore::Element::ariaRequired const): (WebCore::Element::ariaSelected const): (WebCore::Element::ariaSort const): * Tools/DumpRenderTree/TestOptions.cpp * Tools/WebKitTestRunner/TestOptions.cpp

https://bugs.webkit.org/show_bug.cgi?id=296851 rdar://157952768 Reviewed by NOBODY (OOPS!). Adds 'status: developer' feature flag for enumerated ARIA attributes: w3c/aria#2484. The ARIA spec intends to convert the following attributes to be enumerated, i.e., content attributes with permissible keywords and invalid/missing value defaults: - 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 This PR changes ARIA's IDL to use [ReflectSetter] for enumerated attributes in order to implement the desired reflection behavior behind a flag using manual getters; this also allows maintaining current ARIA IDL behavior when the flag is disabled. When ARIA PR WebKit#2484 lands, ARIA's IDL should be updated to use [Reflect, Enumerated] for automatic JS bindings codegen that doesn't need manual code. * Source/WTF/Scripts/Preferences/UnifiedWebPreferences.yaml: * Source/WebCore/accessibility/AriaAttributes.idl: * Source/WebCore/dom/Element.h: * Source/WebCore/dom/Element.cpp: (WebCore::Element::ariaAtomic const): (WebCore::Element::ariaAutoComplete const): (WebCore::Element::ariaBusy const): (WebCore::Element::ariaChecked const): (WebCore::Element::ariaCurrent const): (WebCore::Element::ariaDisabled const): (WebCore::Element::ariaExpanded const): (WebCore::Element::ariaHasPopup const): (WebCore::Element::ariaHidden const): (WebCore::Element::ariaInvalid const): (WebCore::Element::ariaLive const): (WebCore::Element::ariaModal const): (WebCore::Element::ariaMultiLine const): (WebCore::Element::ariaMultiSelectable const): (WebCore::Element::ariaOrientation const): (WebCore::Element::ariaPressed const): (WebCore::Element::ariaReadOnly const): (WebCore::Element::ariaRequired const): (WebCore::Element::ariaSelected const): (WebCore::Element::ariaSort const): * Tools/DumpRenderTree/TestOptions.cpp: * Tools/WebKitTestRunner/TestOptions.cpp:

https://bugs.webkit.org/show_bug.cgi?id=296851 rdar://157952768 Reviewed by Tyler Wilcock and Ryosuke Niwa. Adds 'status: developer' feature flag for enumerated ARIA attributes: w3c/aria#2484. The ARIA spec intends to convert the following attributes to be enumerated, i.e., content attributes with permissible keywords and invalid/missing value defaults: - 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 This PR changes ARIA's IDL to use [ReflectSetter] for enumerated attributes in order to implement the desired reflection behavior behind a flag using manual getters; this also allows maintaining current ARIA IDL behavior when the flag is disabled. When ARIA PR WebKit#2484 lands, ARIA's IDL should be updated to use [Reflect, Enumerated] for automatic JS bindings codegen that doesn't need manual code. * Source/WTF/Scripts/Preferences/UnifiedWebPreferences.yaml: * Source/WebCore/accessibility/AriaAttributes.idl: * Source/WebCore/dom/Element.h: * Source/WebCore/dom/Element.cpp: (WebCore::Element::ariaAtomic const): (WebCore::Element::ariaAutoComplete const): (WebCore::Element::ariaBusy const): (WebCore::Element::ariaChecked const): (WebCore::Element::ariaCurrent const): (WebCore::Element::ariaDisabled const): (WebCore::Element::ariaExpanded const): (WebCore::Element::ariaHasPopup const): (WebCore::Element::ariaHidden const): (WebCore::Element::ariaInvalid const): (WebCore::Element::ariaLive const): (WebCore::Element::ariaModal const): (WebCore::Element::ariaMultiLine const): (WebCore::Element::ariaMultiSelectable const): (WebCore::Element::ariaOrientation const): (WebCore::Element::ariaPressed const): (WebCore::Element::ariaReadOnly const): (WebCore::Element::ariaRequired const): (WebCore::Element::ariaSelected const): (WebCore::Element::ariaSort const): * Tools/DumpRenderTree/TestOptions.cpp: * Tools/WebKitTestRunner/TestOptions.cpp: Canonical link: https://commits.webkit.org/299159@main

rahimabdi · 2025-09-21T06:39:44Z

I've made many updates to this PR addressing outstanding feedback. I've also updated the PR description with a link to an unofficial explainer, details on how to test (via Safari feature flag) and more.

I've also reached out to the Salesforce folks (thanks @gregwhitworth!) to follow up on any impact related to their LWC ARIA polyfill.

I will Agenda+ to discuss these outstanding questions:

aria-haspopup questions
- Mapping of aria-haspopup: should "true" and "menu" be distinct states in terms of IDL?
- Somebody asked why aria-haspopup has a missing value default of null rather than "false". Is this correct?
Specifying undefined in the attribute Values table: does it look OK?
Feedback on the new "Relationship Between the Undefined State and "undefined" String Value" section
Should all ARIA enumerated attributes that support null be specified as an Undefined state? This question applies only to aria-atomic and aria-haspopup.
New empty value default as part of HTML enumerated attribute definition. Any concerns with using this for ARIA attrs that support an empty string keyword?

rahimabdi · 2025-10-01T15:32:04Z

@keithamus @cookiecrook @rahimabdi met with the Salesforce team (@gregwhitworth and others) on Sept 30 2025 to discuss impact/risks for Salesforce frameworks, and to request testing. I've captured meeting notes/next steps in the "Meeting Notes" section in the PR description.

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

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

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

spectranaut removed the Agenda label Sep 2, 2025

rahimabdi closed this Sep 20, 2025

rahimabdi force-pushed the rahim/update-aria-idl-2025 branch from b2ba05c to 38a1bfc Compare September 20, 2025 16:33

github-project-automation bot moved this from Needs Review to Waiting For Implementation in ARIA Normative PR Tracking Sep 20, 2025

Update 'indicates' definition

42a8811

rahimabdi reopened this Sep 20, 2025

Rahim Abdi added 8 commits September 20, 2025 10:09

Update note on boolean-like attrs

3452d91

More updates

c3932e4

Update examples

5755b8f

Minor fixes

bc5fb0b

Add enumerated attr definition

898bbb4

Additional minor fixes

cef6442

Add canonical keywords

c0e0f2a

Add not on undefined value versus Undefined state

5dc7486

rahimabdi requested review from cookiecrook, keithamus, pkra, cyns, annevk and gregwhitworth September 21, 2025 06:33

rahimabdi added the Agenda label Sep 21, 2025

This was referenced Sep 22, 2025

Should ARIA boolean-like attributes behave like HTML boolean attributes? #2639

Open

Editorial: Investigate more effective generation of attribute values tables & IDL details #2642

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

rahimabdi commented Mar 23, 2025 •

edited by pr-preview bot

Loading

Uh oh!

netlify bot commented Mar 23, 2025 •

edited

Loading

Uh oh!

Uh oh!

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!

annevk left a comment

Uh oh!

annevk Apr 28, 2025

Uh oh!

cookiecrook Jul 11, 2025

Uh oh!

cookiecrook Jul 11, 2025

Uh oh!

rahimabdi Sep 20, 2025 •

edited

Loading

Uh oh!

Uh oh!

rahimabdi commented Sep 21, 2025 •

edited

Loading

Uh oh!

rahimabdi commented Oct 1, 2025 •

edited

Loading

Uh oh!

Uh oh!

		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

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!

Mini-Explainer

Summary of Changes

Feature Flag Testing in Safari Tech Preview

Test, Documentation and Implementation tracking

Meeting Notes

ARIA WG & Salesforce Sync (Sept 30 2025)

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!

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!

cookiecrook Jul 11, 2025

Choose a reason for hiding this comment

Uh oh!

cookiecrook Jul 11, 2025

Choose a reason for hiding this comment

Uh oh!

rahimabdi Sep 20, 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 Sep 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

rahimabdi commented Mar 23, 2025 •

edited by pr-preview bot

Loading

netlify bot commented Mar 23, 2025 •

edited

Loading

rahimabdi commented Apr 27, 2025 •

edited

Loading

rahimabdi Sep 20, 2025 •

edited

Loading

rahimabdi commented Sep 21, 2025 •

edited

Loading

rahimabdi commented Oct 1, 2025 •

edited

Loading