Ticket #32600: 32600.4.patch

src/wp-includes/js/wp-a11y.js

@@ -3 +3 @@
 ( function ( wp, $ ) {
         'use strict';
 
-        var $container;
+        var $containerPolite,
+                $containerAssertive;
 
         /**
          * Update the ARIA live notification area text node.
          *
          * @since 4.2.0
+         * @since 4.3.0 Introduced the 'politeness' argument.
          *
-         * @param {String} message
+         * @param {String} message    The message to be announced by Assistive Technologies.
+         * @param {String} politeness Optional. The politeness level for aria-live. Possible values:
+         *                            polite or assertive. Default polite.
          */
-        function speak( message ) {
-                if ( $container ) {
-                        $container.text( message );
+        function speak( message, politeness ) {
+
+                // Clear previous messages if any to allow repeated strings being read out.
+                speakClear();
+
+                if ( $containerAssertive && 'assertive' === politeness ) {
+
+                        // Print the message to the assertive live region.
+                        $containerAssertive.text( message );
+
+                } else if ( $containerPolite ) {
+
+                        // Print the message to the polite live region.
+                        $containerPolite.text( message );
+
                 }
         }
 
         /**
+         * Build the live regions markup.
+         *
+         * @since 4.3.0
+         *
+         * @param {String} id         The id attribute for the live region.
+         * @param {String} politeness The value for the 'aria-live' attribute.
+         *
+         * @return {Object} $container The ARIA live region jQuery object.
+         */
+        function speakAddContainer( id, politeness ) {
+
+                // Create a jQuery live region object.
+                var $container = $( '<div>', {
+                        'id': id,
+                        'role': 'status',
+                        'aria-live': politeness,
+                        'aria-relevant': 'additions text',
+                        'aria-atomic': 'true',
+                        'class': 'screen-reader-text wp-a11y-speak-region'
+                });
+
+                $( document.body ).append( $container );
+
+                return $container;
+        }
+
+        /**
+         * Clear the live regions.
+         *
+         * @since 4.3.0
+         */
+        function speakClear() {
+                $( '.wp-a11y-speak-region' ).text( '' );
+        }
+
+        /**
          * Initialize wp.a11y and define ARIA live notification area.
          *
          * @since 4.2.0
+         * @since 4.3.0 Added the assertive live region.
          */
         $( document ).ready( function() {
-                $container = $( '#wp-a11y-speak' );
+                $containerPolite = $( '#wp-a11y-speak-polite' );
+                $containerAssertive = $( '#wp-a11y-speak-assertive' );
 
-                if ( ! $container.length ) {
-                        $container = $( '<div>', {
-                                id: 'wp-a11y-speak',
-                                role: 'status',
-                                'aria-live': 'polite',
-                                'aria-relevant': 'all',
-                                'aria-atomic': 'true',
-                                'class': 'screen-reader-text'
-                        } );
+                if ( ! $containerPolite.length ) {
+                        $containerPolite = speakAddContainer( 'wp-a11y-speak-polite', 'polite' );
+                }
 
-                        $( document.body ).append( $container );
+                if ( ! $containerAssertive.length ) {
+                        $containerAssertive = speakAddContainer( 'wp-a11y-speak-assertive', 'assertive' );
                 }
-        } );
+        });
 
         wp.a11y = wp.a11y || {};
         wp.a11y.speak = speak;