Media editor: address accessibility review feedback

[ramonjd]

What

Addresses the accessibility feedback from this review comment on the media editor modal. Kudos to @joedolson

Screen reader announcements:

• Only the values you're actually adjusting are announced
• Crop is announced in pixels (e.g. "Crop 800 by 400 pixels") instead of percentages.
• Rotation includes direction (e.g. "Rotated 15 degrees clockwise", "Rotated 10 degrees counterclockwise") and is announced first when adjusting the fine rotation slider.

Resize handle labels:

• Changed from "Resize top-left corner" to "Resize from top-left corner" (and all other positions).

Alt text field:

• The alt text field in the Details panel now shows the same "Describe the purpose of the image" guidance link and "Leave empty if decorative" hint found in the image block.

Not included (follow-up)

inert instead of aria-hidden on non-modal regions — the helper that controls this is shared by every modal in Gutenberg, so it needs its own PR: #79969.

Why

To improve the comprehensibility of the screen reader output.

Test plan

1. Open the media editor modal
2. With a screen reader, verify:
   • Adjusting crop announces pixel dimensions (e.g. "Crop 800 by 400 pixels")
   • Rotating announces direction (e.g. "Rotated 15 degrees clockwise")
   • Zoom-only changes announce just zoom
3. Check the Details panel alt text field shows the guidance link
4. Verify resize handles announce "Resize from [position]"

Tip: you can check the output of the aria live area in the console.

// Rotate snap -90
document.querySelectorAll('[aria-live="polite"]')[1].textContent
> 'Rotated 90 degrees counterclockwise'

// Rotate fine -15
document.querySelectorAll('[aria-live="polite"]')[1].textContent
'Rotated 105 degrees counterclockwise, Zoom 135%'

// Rotate snap +90
document.querySelectorAll('[aria-live="polite"]')[1].textContent
'Rotated 15 degrees counterclockwise, Zoom 136%'

Fixes part of #73771.

Use of AI

Ho utilizzato il Claudio!

[github-actions]

Size Change: +2.9 kB (+0.04%)

Total Size: 7.68 MB

📦 View Changed

Filename	Size	Change
build/scripts/editor/index.min.js	493 kB	+1.24 kB (+0.25%)
build/scripts/media-utils/index.min.js	118 kB	+1.66 kB (+1.43%)

_{compressed-size-action}

[Copilot]

Pull request overview

This PR improves accessibility and guidance within the Gutenberg media editor by refining screen reader announcements in the image cropper, updating resize-handle ARIA labels, and aligning the media Details “Alt text” field help text with other Gutenberg contexts.

Changes:

• Refines useAriaAnnouncer messages to announce only the changed value (crop/zoom/rotation) and adds more descriptive crop and rotation strings.
• Updates resize-handle labels from “Resize {edge/corner}” to “Resize from {edge/corner}”.
• Adds alt-text guidance link + “Leave empty if decorative.” hint to the media Details panel alt text field.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/media-fields/src/alt_text/index.tsx	Adds help text/link for alt text field in media Details.
packages/media-editor/src/image-editor/react/hooks/use-aria-announcer.ts	Updates ARIA live announcements for zoom/crop/rotation/flip changes.
packages/media-editor/src/image-editor/react/hooks/test/use-aria-announcer.ts	Adds/updates unit tests for the new announcer behavior.
packages/media-editor/src/image-editor/react/components/test/cropper.tsx	Updates tests to match new resize-handle labels.
packages/media-editor/src/image-editor/react/components/stencils/test/rectangle-stencil.tsx	Updates stencil tests to match new resize-handle labels.
packages/media-editor/src/image-editor/react/components/stencils/rectangle-stencil.tsx	Changes the resize-handle label strings.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: talldan <talldanwp@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[ramonjd]

e2e tests are failing everywhere not due to this PR

[ramonjd]

Copied from other block media field controls, e.g., https://github.com/WordPress/gutenberg/blob/trunk/packages/format-library/src/image/index.js#L121

[ramonjd]

Duped from above because @wordpress/no-unused-vars-before-return was whining at me.

[andrewserong]

Generally looking pretty good! One thing I noticed while testing is that if I rotate to a positive rotation (e.g. 15 degrees) and then reduce the rotation by a bit it'll announce the rotation in an unexpected way i.e. the following:

Does that happen for you?

Not too sure the cause, but here was what Claude came up with in my local env:

In use-aria-announcer.ts, the direction word is derived from the shortest-arc delta from the previous angle (motion), but the magnitude is derived from the
absolute normalized angle:

 if ( delta > 0 ) return sprintf( __( 'Rotated %d degrees clockwise' ), rounded );        // rounded = abs angle
 if ( delta < 0 ) return sprintf( __( 'Rotated %d degrees counterclockwise' ), 360 - rounded );

These two only agree when the absolute angle happens to sit on the same side as the motion. When they disagree you get a nonsensical ~360 number.

Alt text field changes look good visually to me, though I kind of wish we could keep it to one line (no need to tweak, this is similar to what's in the Image block). Now that there's help text, I'd almost be inclined to put Caption above Alt text, but not a deal breaker (and probably better to keep it as is for now)

[ramonjd]

I noticed while testing is that if I rotate to a positive rotation (e.g. 15 degrees) and then reduce the rotation by a bit it'll announce the rotation in an unexpected way i.e. the following:

Thanks @andrewserong - let me look at that. Some unnecessary normalization going on I think.

[ramonjd]

Some unnecessary normalization going on I think.

This. I was trying to be too clever. The rotation announcement now just reports the visual value, e.g., "Rotation 15 degrees", "Rotation 15 degrees". No more clockwise/counterclockwise direction logic.

> document.querySelectorAll('[aria-live="polite"]')[1].textContent
'Rotation 90 degrees, Crop 617 by 510 pixels'

> document.querySelectorAll('[aria-live="polite"]')[1].textContent
'Rotation 86 degrees'

[andrewserong]

Just working through this bit with Claude again, and I think the calculation here mightn't work correctly when adding a negative rotation to a negative rotation. I.e. snap -90 degrees + -15 degrees seems like it'll result in 75 degrees instead of 105.

I haven't had a chance to verify and I've gotta run, apologies! I can double-check again tomorrow if this is still open.

[ramonjd]

Here's the output of that operation:

// Rotate snap -90
> document.querySelectorAll('[aria-live="polite"]')[1].textContent
'Rotation 270 degrees'
// Rotate fine -15
> document.querySelectorAll('[aria-live="polite"]')[1].textContent
'Zoom 123%, Rotation 255 degrees

So I thought a middle ground would be to output the actual value after action.

Maybe I can write some more tests to cover this

[ramonjd]

And also reinstate direction 😄 -+ should be enough.

[ramonjd]

Okay i've tweaked this to better match Joe's feedback:

// Rotate snap -90
document.querySelectorAll('[aria-live="polite"]')[1].textContent
> 'Rotated 90 degrees counterclockwise'

// Rotate fine -15
document.querySelectorAll('[aria-live="polite"]')[1].textContent
'Rotated 105 degrees counterclockwise, Zoom 135%'

// Rotate snap +90
document.querySelectorAll('[aria-live="polite"]')[1].textContent
'Rotated 15 degrees counterclockwise, Zoom 136%'

Rotation comes first as well.

[andrewserong]

Nearly there: looks like we need to apply the single axis flip (visualDir) to the whole rotation value, not just the offset. While re-testing, my Claude session pointed out that with an image with a horizontal flip applied, if we do a 90 degree rotation, it'd report a rotation in the wrong direction.

I'll push a simple fix and an additional test. I think we can fix it by simplifying to no longer split out the offset and apply the visualDir to the whole rotation value.

[andrewserong]

Pushed, and just added a few extra tests to be sure.

[github-actions]

Flaky tests detected in a355367.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/28997075775
📝 Reported issues:

• [Flaky Test] three users concurrently edit a large post with diverse blocks #78754 in /test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts

[andrewserong]

Just pushed another update after throwing this PR between a Claude and a Codex session which unearthed that we were guarding crop announcements against there being a percentage-based change, but the announcement was pixel based. By making sure that we use the same region for the check and announcement, we can make sure that the crop is announced when making really small (e.g. 1px) crop changes while very zoomed in.

I think this is good to go now, and testing well for me manually 👍

[ramonjd]

Thanks for sending this one home, @andrewserong 🙇🏻