Changeset 64241 for trunk/src/js/_enqueues/wp/theme.js

Timestamp:

10/08/2026 11:33:48 AM (9 days ago)

Author:

afercia

Message:

Administration: Improve focus management and screen reader announcements when navigating the media and theme browsers.

In the various media and theme browsers, the announcements for screen readers were sometimes too noisy because focus was set too often and unnecessarily on some elements. To improve the announcements and move focus only when really necessary, all the media and theme browsers are now standardized to the following pattern:

• Makes sure all the media and theme browsers have a dialog role.
• Keeps the navigation buttons focusable by using aria-disabled instead of disabled.
• Ensures that screen reader announcements are cleaner by keeping focus on the activated control rather than moving it to another element.
• Makes sure initial focus is set to the dialog element when it is opened.
• Makes sure to return focus to the opener control when the dialog is closed.
• Makes sure the opener control is a focusable element.
• Adjusts styles accordingly to take the aria-disabled attribute into account.
• Simplifies the buttons accessible name to: Previous / Next / Close.
• Makes sure the ARIA live regions are not hidden when they inherit visibility: hidden.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13816

Props sukhendu2002, khokansardar, afercia.
Fixes #65746.

File:

• trunk/src/js/_enqueues/wp/theme.js (modified) (11 diffs)

trunk/src/js/_enqueues/wp/theme.js

@@ -481 +481 @@
                 }
 
-                // Set focused theme to current element.
+                // Store the theme that had focus when expand is called.
                 themes.focusedTheme = this.$el;
 
@@ -521 +521 @@
                 event = event || window.event;
 
-                // Set focus to current theme.
+                // Store the theme that had focus when preview is called.
                 themes.focusedTheme = this.$el;
 
@@ -621 +621 @@
                         previousThemeButton
                                 .addClass( 'disabled' )
-                                .prop( 'disabled', true );
-
-                        nextThemeButton.trigger( 'focus' );
+                                .attr( 'aria-disabled', true )
+                                .trigger( 'focus' );
                 }
 
@@ -630 +629 @@
                         nextThemeButton
                                 .addClass( 'disabled' )
-                                .prop( 'disabled', true );
-
-                        previousThemeButton.trigger( 'focus' );
+                                .attr( 'aria-disabled', true )
+                                .trigger( 'focus' );
                 }
         },
@@ -726 +724 @@
         // Set initial focus and constrain tabbing within the theme browser modal.
         containFocus: function( $el ) {
-
-                // Set initial focus on the primary action control.
-                _.delay( function() {
-                        $( '.theme-overlay' ).trigger( 'focus' );
-                }, 100 );
+                // Set initial focus on the theme overlay modal dialog, only on first render.
+                var $themeOverlay = $( '.theme-overlay' );
+                if ( $themeOverlay.hasClass( 'theme-overlay-initial' ) ) {
+                        _.delay( function() {
+                                $themeOverlay.trigger( 'focus' ).removeClass( 'theme-overlay-initial' );
+                        }, 100 );
+                }
+
 
                 // Constrain tabbing within the modal.
@@ -786 +787 @@
                                 document.body.scrollTop = scroll;
 
-                                // Return focus to the theme div.
+                                // Return focus to the opener theme 'more-details' button.
                                 if ( themes.focusedTheme ) {
-                                        themes.focusedTheme.find('.more-details').trigger( 'focus' );
+                                        themes.focusedTheme.find( '.more-details' ).trigger( 'focus' );
                                 }
+
+                                // Add back the `theme-overlay-initial` class for the theme overlay.
+                                $( '.theme-overlay' ).addClass( 'theme-overlay-initial' );
                         });
                 }
@@ -804 +808 @@
                         this.$el.find( '.left' )
                                 .addClass( 'disabled' )
-                                .prop( 'disabled', true );
+                                .attr( 'aria-disabled', true );
                 }
                 if ( this.model.cid === this.model.collection.at( this.model.collection.length - 1 ).cid ) {
                         this.$el.find( '.right' )
                                 .addClass( 'disabled' )
-                                .prop( 'disabled', true );
+                                .attr( 'aria-disabled', true );
                 }
         },
@@ -961 +965 @@
                 this.$el.fadeIn( 200, function() {
                         $body.addClass( 'theme-installer-active full-overlay-active' );
+                        // Set initial focus on the theme installer overlay modal dialog.
+                        self.$el.trigger( 'focus' );
                 });
 
@@ -977 +983 @@
                         $( 'body' ).removeClass( 'theme-installer-active full-overlay-active' );
 
-                        // Return focus to the theme div.
+                        // Return focus to the opener theme 'more-details' button.
                         if ( themes.focusedTheme ) {
-                                themes.focusedTheme.find('.more-details').trigger( 'focus' );
+                                themes.focusedTheme.find( '.more-details' ).trigger( 'focus' );
                         }
                 }).removeClass( 'iframe-ready' );
@@ -1355 +1361 @@
                         // Trigger a route update for the current model.
                         self.theme.trigger( 'theme:expand', nextModel.cid );
+                        // Set focus again to the 'Next' navigation button after the view fully re-rendeers.
+                        $( '.theme-header .right' ).trigger( 'focus' );
                         themes.announceThemeDebounced( nextModel );
                 }
@@ -1390 +1398 @@
                         // Trigger a route update for the current model.
                         self.theme.trigger( 'theme:expand', previousModel.cid );
+                        // Set focus again to the 'Previous' navigation button after the view fully re-rendeers.
+                        $( '.theme-header .left' ).trigger( 'focus' );
                         themes.announceThemeDebounced( previousModel );
                 }