fix(pending-state): correct reflection of aria in pending controller #5730

caseyisonit · 2025-09-15T22:13:47Z

Description

This PR fixes aria-label handling issues in button components and improves accessibility for pending state controllers. The changes ensure that aria-labels are properly managed and preserved across component state changes, providing better screen reader support.

Key Changes:

Button Component (@spectrum-web-components/button):

Fixed timing of aria-label updates to occur after slot content changes are processed, preventing race conditions
Added label property support for programmatic aria-label control in Storybook
Added comprehensive tests for aria-label behavior during content changes
Moved aria-label management logic to execute after slot content processing

PendingState Controller (@spectrum-web-components/reactive-controllers):

Improved aria-label caching logic to better handle dynamic label changes
Changed progress circle from aria-valuetext to aria-label for better accessibility compliance
Enhanced caching mechanism to preserve user-set aria-labels during pending states
Added more robust logic for determining when to cache aria-labels

Motivation and context

The previous implementation had timing issues, allowing aria-label updates to occur before slot content changes were fully processed, leading to inconsistent accessibility behavior. Additionally, the pending state controller was using aria-valuetext instead of aria-label for progress indicators, which is not the recommended approach for accessibility.

These changes ensure that:

Screen readers receive consistent and accurate aria-label information
User-set aria-labels are properly preserved during component state changes
Progress indicators follow accessibility best practices
Dynamic content changes don't interfere with aria-label management

Related issue(s)

fixes [5620]
resolves SWC-1039

Screenshots (if appropriate)

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
I have added automated tests to cover my changes.
I have included a well-written changeset if my change needs to be published.
I have included updated documentation if my change required it.

Reviewer's checklist

Includes a Github Issue with appropriate flag or Jira ticket number without a link
Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
Automated tests cover all use cases and follow best practices for writing
Validated on all supported browsers
All VRTs are approved before the author can update Golden Hash

Manual review test cases

Button aria-label timing test

Go to the button Storybook stories
Set a label property on a button with slot content
Change the slot content dynamically
Verify that the aria-label remains consistent and doesn't get overridden

Pending state aria-label preservation test

Go to any component that uses the PendingState controller (like buttons with pending states)
Set a custom aria-label on the component
Trigger the pending state
Verify that the custom aria-label is cached and restored when pending state ends

Progress circle accessibility test

Go to components with pending states
Use a screen reader to navigate to the progress indicator
Verify that the progress circle announces properly with aria-label instead of aria-valuetext

Dynamic content changes test

Create a button with both slot content and a label property
Dynamically change the slot content multiple times
Verify that the aria-label from the label property is preserved throughout

Device review

Did it pass in Desktop?
Did it pass in (emulated) Mobile?
Did it pass in (emulated) iPad?

changeset-bot · 2025-09-15T22:13:51Z

🦋 Changeset detected

Latest commit: e327b6e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 84 packages

Name	Type
@spectrum-web-components/button	Patch
@spectrum-web-components/reactive-controllers	Patch
@spectrum-web-components/action-bar	Patch
@spectrum-web-components/action-button	Patch
@spectrum-web-components/alert-banner	Patch
@spectrum-web-components/alert-dialog	Patch
@spectrum-web-components/button-group	Patch
@spectrum-web-components/coachmark	Patch
@spectrum-web-components/dialog	Patch
@spectrum-web-components/infield-button	Patch
@spectrum-web-components/picker-button	Patch
@spectrum-web-components/picker	Patch
@spectrum-web-components/search	Patch
@spectrum-web-components/tags	Patch
@spectrum-web-components/toast	Patch
example-project-rollup	Patch
example-project-webpack	Patch
@spectrum-web-components/bundle	Patch
@spectrum-web-components/accordion	Patch
@spectrum-web-components/action-group	Patch
@spectrum-web-components/color-area	Patch
@spectrum-web-components/color-slider	Patch
@spectrum-web-components/color-wheel	Patch
@spectrum-web-components/combobox	Patch
@spectrum-web-components/contextual-help	Patch
@spectrum-web-components/field-label	Patch
@spectrum-web-components/icon	Patch
@spectrum-web-components/menu	Patch
@spectrum-web-components/meter	Patch
@spectrum-web-components/number-field	Patch
@spectrum-web-components/overlay	Patch
@spectrum-web-components/progress-bar	Patch
@spectrum-web-components/radio	Patch
@spectrum-web-components/sidenav	Patch
@spectrum-web-components/slider	Patch
@spectrum-web-components/swatch	Patch
@spectrum-web-components/tabs	Patch
@spectrum-web-components/tooltip	Patch
@spectrum-web-components/tray	Patch
@spectrum-web-components/story-decorator	Patch
@spectrum-web-components/grid	Patch
@spectrum-web-components/vrt-compare	Patch
@spectrum-web-components/action-menu	Patch
@spectrum-web-components/custom-vars-viewer	Patch
documentation	Patch
@spectrum-web-components/checkbox	Patch
@spectrum-web-components/icons-ui	Patch
@spectrum-web-components/icons-workflow	Patch
@spectrum-web-components/table	Patch
@spectrum-web-components/textfield	Patch
@spectrum-web-components/breadcrumbs	Patch
@spectrum-web-components/popover	Patch
@spectrum-web-components/truncated	Patch
@spectrum-web-components/top-nav	Patch
@spectrum-web-components/card	Patch
@spectrum-web-components/switch	Patch
@spectrum-web-components/help-text	Patch
@spectrum-web-components/color-field	Patch
@spectrum-web-components/field-group	Patch
@spectrum-web-components/eslint-plugin	Patch
@spectrum-web-components/asset	Patch
@spectrum-web-components/avatar	Patch
@spectrum-web-components/badge	Patch
@spectrum-web-components/clear-button	Patch
@spectrum-web-components/close-button	Patch
@spectrum-web-components/color-handle	Patch
@spectrum-web-components/color-loupe	Patch
@spectrum-web-components/divider	Patch
@spectrum-web-components/dropzone	Patch
@spectrum-web-components/icons	Patch
@spectrum-web-components/iconset	Patch
@spectrum-web-components/illustrated-message	Patch
@spectrum-web-components/link	Patch
@spectrum-web-components/modal	Patch
@spectrum-web-components/progress-circle	Patch
@spectrum-web-components/split-view	Patch
@spectrum-web-components/status-light	Patch
@spectrum-web-components/thumbnail	Patch
@spectrum-web-components/underlay	Patch
@spectrum-web-components/base	Patch
@spectrum-web-components/opacity-checkerboard	Patch
@spectrum-web-components/shared	Patch
@spectrum-web-components/styles	Patch
@spectrum-web-components/theme	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2025-09-15T22:15:32Z

📚 Branch Preview

🔍 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-5730

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

github-actions · 2025-09-15T22:18:35Z

Tachometer results

Currently, no packages are changed by this PR...

tools/reactive-controllers/src/PendingState.ts

Rajdeepc · 2025-09-22T06:41:47Z

.changeset/seven-nails-wave.md

+'@spectrum-web-components/button': patch
+'@spectrum-web-components/reactive-controllers': patch


nit: Will this be read with our current changelog script? Would you prefer adding separate changeset for each package instead?

there are other changesets with mulitple packages, i dont think it should be an issue

I think what Rajdeep means is, even though this works, our change log script does not pick up multiple packages (only the first one).

Rajdeepc

I really like how this has come together.
One suggestion: Would you like to add a quick screen reader test video to the PR. This would help the original reporter (and future contributors) to verify the behavior.

rubencarvalho

Nice work! I left one blocking comment: could we confirm the double label behavior?

packages/button/stories/template.ts

packages/button/stories/index.ts

tools/reactive-controllers/src/PendingState.ts

rubencarvalho · 2025-09-23T15:22:35Z

tools/reactive-controllers/src/PendingState.ts

+            cached: string | null,
+            current: string | null,
+            pending: string | undefined
+        ): string | boolean | null {


Are the possible return values accurate? string | boolean | null?

rubencarvalho · 2025-09-23T15:23:37Z

tools/reactive-controllers/src/PendingState.ts

+            pending: string | undefined
+        ): string | boolean | null {
+            return (
+                (!cached && current && current !== pending) ||


current && ... treats "" as false. Is an empty string invalid? Or do we need to treat null/undefined differently from an empty string?

If an empty string, maybe we can add a test to cover that?

current !== "" && ...

rubencarvalho · 2025-09-23T15:27:16Z

tools/reactive-controllers/src/PendingState.ts

+     * Renders the pending state UI. The aria-valuetext is needed for Firefox
     * @returns A TemplateResult representing the pending state UI.
+     *
+     * @TODO: [SWC-1255] This should now be using the progress-circle component. It should be using an animated SVG icon with correct role and aria.


nit:

Suggested change

* @TODO: [SWC-1255] This should now be using the progress-circle component. It should be using an animated SVG icon with correct role and aria.

* @TODO: [SWC-1255] This should not be using the progress-circle component. It should be using an animated SVG icon with correct role and aria.

(also, this todo is very prescriptive of the solution, even though I don't think we have complete clarity on the path forward her)

i can change the language

rubencarvalho · 2025-09-23T15:40:35Z

tools/reactive-controllers/src/PendingState.ts

    public cachedAriaLabel: string | null = null;
    /**
-     * Renders the pending state UI.
+     * Renders the pending state UI. The aria-valuetext is needed for Firefox


The aria-valuetext is needed for Firefox

I'm curious, why?

because firefox reads indeterminate as 50 and value text will override that for screen readers, again this is part of the accessibility issue with using pending-circle

role = ""
aria-hidden="true"

fix(pending-state): correct reflection of aria in pending controller

ba8e5c9

Rajdeepc requested changes Sep 17, 2025

View reviewed changes

tools/reactive-controllers/src/PendingState.ts Show resolved Hide resolved

tools/reactive-controllers/src/PendingState.ts Outdated Show resolved Hide resolved

caseyisonit added 4 commits September 19, 2025 13:11

chore: cache aria helper, label to updated lifecycle

f380b21

Merge branch 'main' into caseyisonit/button-pending-aria-fix

bc64d9a

chore: add changeset

c3d6a48

chore: update tests

b6e5f99

caseyisonit marked this pull request as ready for review September 19, 2025 19:46

caseyisonit requested a review from a team as a code owner September 19, 2025 19:46

caseyisonit requested a review from Rajdeepc September 19, 2025 19:47

caseyisonit added 2 commits September 19, 2025 15:10

chore: update tests

b3efeed

chore: remove console log

44dfa1e

Rajdeepc reviewed Sep 22, 2025

View reviewed changes

Rajdeepc approved these changes Sep 22, 2025

View reviewed changes

rubencarvalho requested changes Sep 22, 2025

View reviewed changes

packages/button/stories/template.ts Outdated Show resolved Hide resolved

packages/button/stories/index.ts Outdated Show resolved Hide resolved

tools/reactive-controllers/src/PendingState.ts Outdated Show resolved Hide resolved

caseyisonit added 4 commits September 22, 2025 12:53

chore: remove eslint comments and unnecessary update lifecycle

6a9858e

chore: fix a11y tests

8bf7e04

chore: changeset update

bdc9eee

chore: add ticket number to todo

e327b6e

caseyisonit requested a review from rubencarvalho September 22, 2025 20:00

blunteshwar approved these changes Sep 22, 2025

View reviewed changes

rubencarvalho reviewed Sep 23, 2025

View reviewed changes

This was referenced Sep 24, 2025

fix(button): update aria-label when label changes #5691

Open

fix: base-button, update aria label on updated event. This also updated attr on slotchange event #5674

Open

		'@spectrum-web-components/button': patch
		'@spectrum-web-components/reactive-controllers': patch

	* @TODO: [SWC-1255] This should now be using the progress-circle component. It should be using an animated SVG icon with correct role and aria.
	* @TODO: [SWC-1255] This should not be using the progress-circle component. It should be using an animated SVG icon with correct role and aria.

fix(pending-state): correct reflection of aria in pending controller #5730

Are you sure you want to change the base?

fix(pending-state): correct reflection of aria in pending controller #5730

Conversation

caseyisonit commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Key Changes:

Motivation and context

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Reviewer's checklist

Manual review test cases

Device review

Uh oh!

changeset-bot bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview

🔍 Visual Regression Test Results

Uh oh!

github-actions bot commented Sep 15, 2025

Tachometer results

Uh oh!

Uh oh!

Uh oh!

Rajdeepc Sep 22, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rajdeepc left a comment • 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!

rubencarvalho left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

caseyisonit commented Sep 15, 2025 •

edited

Loading

changeset-bot bot commented Sep 15, 2025 •

edited

Loading

github-actions bot commented Sep 15, 2025 •

edited

Loading

Rajdeepc Sep 22, 2025 •

edited

Loading

Rajdeepc left a comment •

edited

Loading