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

[rahimabdi]

Closes #2281 Closes #2279

Mini-Explainer

See ARIA IDL updates 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.

• [x] "author MUST" tests: N/A
• [x] "user agent MUST" tests: https://github.com/web-platform-tests/wpt/pull/54119
• [ ] Browser implementations (link to issue or commit):
  • [x] WebKit: https://bugs.webkit.org/show_bug.cgi?id=296851 (Shipping behind feature flag)
  • [ ] Gecko:
  • [ ] Blink:
• [x] Does this need AT implementations? No
• [ ] Related APG Issue/PR:
• [ ] MDN Issue/PR:
• [ ] Further outreach?
  • [x] @rahimabdi outreach to Salesforce contributors (@gregwhitworth et al) re: potential webcompat
  • [ ] Salesforce response pending re: testing the new feature flag in Safari Tech Preview

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[bot]]

✅ Deploy Preview for wai-aria ready!

Name	Link
🔨 Latest commit	5dc748615bcbb1d3642855c9c3ddf7a02ba4900c
🔍 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.

[rahimabdi]

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

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

[rahimabdi]

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

[cyns]

@aleventhal you may want to review this

[spectranaut]

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

[spectranaut]

Discussed briefly: https://www.w3.org/2025/06/26-aria-minutes.html#768c

Next step to write tentative tests?

[rahimabdi]

It appears that many of these attributes have secondary/tertiary keywords that map to an existing state. For example, for aria-checked, both the empty string and the string "undefined" are both "false", which is the same as the invalid value default:

• Keywords: { "true", "false", "mixed", "", "undefined" }
• No missing value default (value becomes null)
• No invalid value default (value becomes null)

Question for the ARIA WG: would it be preferable to explicitly state these keywords and their state mapping in spec, or should they be omitted?

Approach 1 - Explicitly state every single keyword/state for each enumerated attribute (simplified example):

aria-checked:

• This attribute's keywords are "true" (True), "false" (False), "mixed" (Mixed), "" (False) and "undefined" (False).
• The attribute's missing value default and invalid value default are the Undefined state (null).

Approach 2 - Omit the extra keywords that have the same state mapping (simplified example):

aria-checked:

• This attribute's keywords are "true" (True), "false" (False), "mixed" (Mixed).
• The attribute's missing value default and invalid value default are the Undefined state (null).

Approach 3 - Omit the extra keywords that have the same state mapping, but call out the extra keywords for clarity (simplified example):

aria-checked:

• This attribute's keywords are "true" (True), "false" (False), "mixed" (Mixed).
• The attribute's missing value default and invalid value default are the Undefined state (null).
• Note: The empty string and "undefined" must return the False state (invalid value default).

[annevk]

I think supporting the empty string as a valid keyword makes sense, but "undefined" not so much.

[spectranaut]

Notes from today's meeting: https://www.w3.org/2025/08/14-aria-minutes.html#367f

[rahimabdi]

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]

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

[spectranaut]

Discussed Rahim's questions above in today's meeting: https://www.w3.org/2025/10/09-aria-minutes.html#31d8

[spectranaut]

@rahimabdi did all of your questions get answered?