[Summary view] [Print] [Text view]

   1  /**
   2   * @output wp-includes/js/wp-a11y.js
   3   */
   4  
   5  /** @namespace wp */
   6  window.wp = window.wp || {};
   7  
   8  ( function ( wp, $ ) {
   9      'use strict';
  10  
  11      var $containerPolite,
  12          $containerAssertive,
  13          previousMessage = '';
  14  
  15      /**
  16       * Update the ARIA live notification area text node.
  17       *
  18       * @since 4.2.0
  19       * @since 4.3.0 Introduced the 'ariaLive' argument.
  20       *
  21       * @param {String} message    The message to be announced by Assistive Technologies.
  22       * @param {String} [ariaLive] The politeness level for aria-live. Possible values:
  23       *                            polite or assertive. Default polite.
  24       * @returns {void}
  25       */
  26  	function speak( message, ariaLive ) {
  27          // Clear previous messages to allow repeated strings being read out.
  28          clear();
  29  
  30          // Remove HTML tags, ensuring only text is sent to screen readers.
  31          message = wp.sanitize.stripTagsAndEncodeText( message );
  32  
  33          /*
  34           * Safari 10+VoiceOver don't announce repeated, identical strings. We use
  35           * a `no-break space` to force them to think identical strings are different.
  36           * See ticket #36853.
  37           */
  38          if ( previousMessage === message ) {
  39              message = message + '\u00A0';
  40          }
  41  
  42          previousMessage = message;
  43  
  44          if ( $containerAssertive && 'assertive' === ariaLive ) {
  45              $containerAssertive.text( message );
  46          } else if ( $containerPolite ) {
  47              $containerPolite.text( message );
  48          }
  49      }
  50  
  51      /**
  52       * Build the live regions markup.
  53       *
  54       * @since 4.3.0
  55       *
  56       * @param {String} ariaLive Optional. Value for the 'aria-live' attribute, default 'polite'.
  57       *
  58       * @return {Object} $container The ARIA live region jQuery object.
  59       */
  60  	function addContainer( ariaLive ) {
  61          ariaLive = ariaLive || 'polite';
  62  
  63          var $container = $( '<div>', {
  64              'id': 'wp-a11y-speak-' + ariaLive,
  65              'aria-live': ariaLive,
  66              'aria-relevant': 'additions text',
  67              'aria-atomic': 'true',
  68              'class': 'screen-reader-text wp-a11y-speak-region'
  69          });
  70  
  71          $( document.body ).append( $container );
  72          return $container;
  73      }
  74  
  75      /**
  76       * Clear the live regions.
  77       *
  78       * @since 4.3.0
  79       */
  80  	function clear() {
  81          $( '.wp-a11y-speak-region' ).text( '' );
  82      }
  83  
  84      /**
  85       * Initialize wp.a11y and define ARIA live notification area.
  86       *
  87       * @since 4.2.0
  88       * @since 4.3.0 Added the assertive live region.
  89       */
  90      $( document ).ready( function() {
  91          $containerPolite = $( '#wp-a11y-speak-polite' );
  92          $containerAssertive = $( '#wp-a11y-speak-assertive' );
  93  
  94          if ( ! $containerPolite.length ) {
  95              $containerPolite = addContainer( 'polite' );
  96          }
  97  
  98          if ( ! $containerAssertive.length ) {
  99              $containerAssertive = addContainer( 'assertive' );
 100          }
 101      });
 102  
 103      /** @namespace wp.a11y */
 104      wp.a11y = wp.a11y || {};
 105      wp.a11y.speak = speak;
 106  
 107  }( window.wp, window.jQuery ));