Quantity Spin Button Example: Add ariaNotify progressive enhancement

[adampage]

Migrated from fork PR #3455 to a branch in the main repo.

Preview deployed to the Quantity Spin Button Example.

---

Re: #3414 and its discussion in the Wed, July 22, 2026 APG TF call.

A few quick notes:

• By default, the main implementation change —  done in b915a5b — conservatively assumes that ariaNotify is not supported by the user’s browser. It leaves <output> live regions in the example’s static HTML and only removes them from the DOM (and bypasses their corresponding content injections) after confirming that ariaNotify is available.

• I updated the regression tests to account for either announcement technique depending on the test browser’s capabilities, which was fun. 😅

• I also added some new content in the Accessibility Features section.

• While testing, I noticed that the latest macOS Safari no longer announces the updated value as a percentage when aria-valuetext is added. So I indulged in a little scope creep to add aria-valuetext functionality, additional documentation, and regression tests. Would it be better for me to extract this out as a separate PR?
  Aug 19: removed aria-valuetext per APG meeting decision

cc: @mcking65

---

WAI Preview Link (Last built on Wed, 19 Aug 2026 16:41:23 GMT).

[mcking65]

We should discuss the use of aria-valuetext given that the spec says:

Authors SHOULD only set the aria-valuetext attribute when the rendered value cannot be meaningfully represented as a number. For example, a slider might have rendered values of small, medium, and large. In this case, the values of aria-valuenow could range from 1 through 3, which indicate the position of each value in the value space, but the aria-valuetext would be one of the strings: small, medium, or large.

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed PR 3461: Quantity Spin Button Example: Add ariaNotify progressive enhancement.

The full IRC log of that discussion

<Zakim> agendum 3 -- PR 3461: Quantity Spin Button Example: Add ariaNotify progressive enhancement -- taken up [from agendabot]
<jugglinmike> github: https://github.com//pull/3461
<jugglinmike> Matt_King: This is an awesome pull request by Adam
<jugglinmike> Matt_King: I added one comment but haven't performed a formal review, yet
<jugglinmike> Matt_King: I believe we have yet to assign a couple reviewers
<jugglinmike> Adam: I reassigned you, Matt_King, and Joe after I re-created the pull request
<jugglinmike> Matt_King: Got it. Everything about aria-notify looks good to me
<jugglinmike> jongund: If you need any additional help on this, I can do that
<jugglinmike> Adam: Thank you jongund, I'll add you
<jugglinmike> Adam: The gist of these changes is that we have this example of a spin button that is a quantity field allowing the user to increment/decrement a field. In the current implementation, we notify about those operations with an aria-live region
<jugglinmike> Adam: It's been published for about a year.
<jugglinmike> Adam: In this pull request, I've integrated aria-notify as a progressive enhancement. That means the live region is assumed by default, but if aria-notify is detected, then we remove the live regions
<jugglinmike> Adam: I also updated the regression tests accordingly
<jugglinmike> Adam: And I updated the prose of the example page to talk about aria-notify
<jugglinmike> Adam: And then finally, in a little bit of scope creep, I added aria-valuetext after discovering that macOS VoiceOver (which had previously announced the updated values in percentage terms), will use aria-valuetext as a workaround
<jugglinmike> Adam: Matt_King pointed out that VoiceOver's behavior is actually in violation of ARIA, so I am prepared to remove the workaround I added which depends on it
<jugglinmike> Matt_King: One of the things we don't do in APG is hacks due to the potential consequences when implementations are fixed
<jugglinmike> Matt_King: In this case, one of the tests in ARIA-AT is that if valuetext is used, it should ignore valuemin and valuemax in additional to valuenow (since they don't make sense in that situation)
<jugglinmike> Matt_King: If all the screen readers were correctly ignoring valuemin and valuemax when valuetext is present, then this workaround would have side-effects when this behavior is fixed
<jugglinmike> Adam: Ah, yes, I'd forgotten about that. I'll remove the workaround
<jugglinmike> Matt_King: So, the live regions only operate when you use the buttons (as opposed to when you use the edit field), right?
<jugglinmike> Adam: Right
<jugglinmike> Matt_King: Okay, so they're particularly valuable for the touch screen reader who would not be using a keyboard
<jugglinmike> Adam: Right, neither entering a number into the input nor using the arrow keys on the keyboard would trigger the live regions
<Daniel> q+
<jugglinmike> Matt_King: I noticed your link to MDN. I think it's a good choice, but maybe we should talk about it
<jugglinmike> Adam: I chose that because ARIA doesn't have a lot of prose on this topic
<jugglinmike> ack Daniel
<jugglinmike> Daniel: Yes, that's been flagged, and we're working on it
<jugglinmike> Daniel: We have prose under review
<jugglinmike> Matt_King: Does that text link to MDN?
<jugglinmike> Daniel: No, it does not
<Daniel> q+ Lola
<Daniel> ack me
<jugglinmike> Adam: Maybe I should just change the link now to the ARIA spec since that is the more canonical source. I suspect that anyone reading this will refer to MDN if they are unsatisfied by the spec
<jugglinmike> ack lola
<jugglinmike> lola: I want to push back slightly on using the ARIA spec rather than MDN
<jugglinmike> lola: This has come up in other groups
<Daniel> ack lola
<jugglinmike> lola: The people who we can assume read APG are more likely to be developers rather than spec editors. While I agree that the people who are reading APG and the people reading MDN are a tight circle, I wouldn't want to assume that. I know groups of developers who don't know MDN and groups of developers who don't know APG
<Daniel> q+
<jugglinmike> lola: Because this is a web developer resource and not a browser-developer resource, I would vote for MDN
<jugglinmike> Adam: Thanks lola, I appreciate that
<jugglinmike> Matt_King: For this particular case, because it is a JavaScript method call... Normally, for most other things (if you're talking about a state, a role), then we point to the ARIA spec as a technical source of the information. The purpose of the APG is to explain the spec
<jugglinmike> Matt_King: The purpose of this example is a different case. I agree with what you're saying lola. You would point to ARIA if you are a developer and you want more details about using the API. We don't have that in the APG. It might be best in the long term to point to a page on APG, but that is currently itself only available in a pull request.
<jugglinmike> Matt_King: I don't think you'll get what you want when you click on the link if it goes to the ARIA spec
<jugglinmike> Matt_King: But everything is in pull requests right now, so we can't link to it
<jugglinmike> Matt_King: I wonder if we should leave it as it is (pointing it to MDN) and file an issue to reconsider this in 6 months to a year (or after we land the aria-notify section of APG)... Actually, we could probably tie the issue to that pull request
<jugglinmike> ack Daniel
<jugglinmike> Daniel: I understand that ARIA currently doesn't have the information, but when we do, I think there's a consistency aspect. ARIA Practices exists because there are ARIA features for which we need to build examples.
<jugglinmike> Daniel: This isn't a case where we need to choose one or the other, either. We can link to both
<jugglinmike> Daniel: I'm happy to leave it as it is for now and revisit when the ARIA spec change lands
<jugglinmike> Matt_King: Okay, so for this pull request, we'll leave it as-is, and I'll take an action item to file an issue
<jugglinmike> Daniel: I can raise that issue, if you like
<jugglinmike> Matt_King: Sounds good; thank you
<jugglinmike> q?
<jugglinmike> Adam: jongund and Matt_King, if you wait a day, then I can remove the aria-valuetext by the end of today
<jugglinmike> zakim, next item