resources/src/mediawiki.util/jquery.accessKeyLabel.js

   1 /**
   2  * jQuery plugin to update the tooltip to show the correct access key
   3  */
   4
   5 // Whether to use 'test-' instead of correct prefix (for unit tests)
   6 let testMode = false;
   7
   8 let cachedModifiers;
   9
  10 /**
  11  * Find the modifier keys that need to be pressed together with the accesskey to trigger the input.
  12  *
  13  * The result is dependent on the ua paramater or the current platform.
  14  * For browsers that support accessKeyLabel, #getAccessKeyLabel never calls here.
  15  * Valid key values that are returned can be: ctrl, alt, option, shift, esc
  16  *
  17  * @private
  18  * @param {Object|undefined} [nav] A Navigator object with `userAgent` and `platform` properties.
  19  * @return {string} Label with dash-separated segments in this order: ctrl, option, alt, shift, esc
  20  */
  21 function getAccessKeyModifiers( nav ) {
  22         if ( !nav && cachedModifiers ) {
  23                 return cachedModifiers;
  24         }
  25
  26         const profile = $.client.profile( nav );
  27         let accessKeyModifiers;
  28
  29         switch ( profile.name ) {
  30                 // Historical: Opera 8-13 used shift-esc- (Presto engine, no longer supported).
  31                 // Opera 15+ (Blink engine) matches Chromium.
  32                 // Historical: Konqueror 3-4 (WebKit) behaved the same as Safari (no longer supported).
  33                 // Konqueror 18+ (QtWebEngine/Chromium engine) is profiled as 'chrome',
  34                 // and matches Chromium behaviour.
  35                 case 'opera':
  36                 case 'chrome':
  37                         if ( profile.platform === 'mac' ) {
  38                                 // Chromium on macOS
  39                                 accessKeyModifiers = 'ctrl-option';
  40                         } else {
  41                                 // Chromium on Windows or Linux
  42                                 // (both alt- and alt-shift work, but alt with E, D, F etc does not
  43                                 // work since they are native browser shortcuts as well, so advertise
  44                                 // alt-shift- instead)
  45                                 accessKeyModifiers = 'alt-shift';
  46                         }
  47                         break;
  48                 // Historical: Firefox 1.x used alt- (no longer supported).
  49                 case 'firefox':
  50                 case 'iceweasel':
  51                         if ( profile.platform === 'mac' ) {
  52                                 if ( profile.versionNumber < 14 ) {
  53                                         accessKeyModifiers = 'ctrl';
  54                                 } else {
  55                                         // Firefox 14+ on macOS
  56                                         accessKeyModifiers = 'ctrl-option';
  57                                 }
  58                         } else {
  59                                 // Firefox 2+ on Windows or Linux
  60                                 accessKeyModifiers = 'alt-shift';
  61                         }
  62                         break;
  63                 // Historical: Safari <= 3 on Windows used alt- (no longer supported).
  64                 // Historical: Safari <= 3 on macOS used ctrl- (no longer supported).
  65                 case 'safari':
  66                         // Safari 4+ (WebKit 526+) on macOS
  67                         accessKeyModifiers = 'ctrl-option';
  68                         break;
  69                 case 'msie':
  70                 case 'edge':
  71                         accessKeyModifiers = 'alt';
  72                         break;
  73                 default:
  74                         accessKeyModifiers = profile.platform === 'mac' ? 'ctrl' : 'alt';
  75                         break;
  76         }
  77
  78         if ( !nav ) {
  79                 // If not for a custom UA string, cache and re-use
  80                 cachedModifiers = accessKeyModifiers;
  81         }
  82         return accessKeyModifiers;
  83 }
  84
  85 /**
  86  * Get the access key label for an element.
  87  *
  88  * Will use native accessKeyLabel if available (currently only in Firefox 8+),
  89  * falls back to #getAccessKeyModifiers.
  90  *
  91  * @private
  92  * @param {HTMLElement} element Element to get the label for
  93  * @return {string} Access key label
  94  */
  95 function getAccessKeyLabel( element ) {
  96         // abort early if no access key
  97         if ( !element.accessKey ) {
  98                 return '';
  99         }
 100         // use accessKeyLabel if possible
 101         // https://html.spec.whatwg.org/multipage/interaction.html#dom-accesskeylabel
 102         if ( !testMode && element.accessKeyLabel ) {
 103                 return element.accessKeyLabel;
 104         }
 105         return ( testMode ? 'test' : getAccessKeyModifiers() ) + '-' + element.accessKey;
 106 }
 107
 108 /**
 109  * Update the title for an element (on the element with the access key or it's label) to show
 110  * the correct access key label.
 111  *
 112  * @private
 113  * @param {HTMLElement} element Element with the accesskey
 114  * @param {HTMLElement} titleElement Element with the title to update (may be the same as `element`)
 115  */
 116 function updateTooltipOnElement( element, titleElement ) {
 117         const oldTitle = titleElement.title;
 118         if ( !oldTitle ) {
 119                 // don't add a title if the element didn't have one before
 120                 return;
 121         }
 122
 123         const separatorMsg = mw.message( 'word-separator' ).plain();
 124         const parts = ( separatorMsg + mw.message( 'brackets' ).plain() ).split( '$1' );
 125
 126         const regexp = new RegExp( parts.map( mw.util.escapeRegExp ).join( '.*?' ) + '$' );
 127         let newTitle = oldTitle.replace( regexp, '' );
 128         const accessKeyLabel = getAccessKeyLabel( element );
 129
 130         if ( accessKeyLabel ) {
 131                 // Should be build the same as in Linker::titleAttrib
 132                 newTitle += separatorMsg + mw.message( 'brackets', accessKeyLabel ).plain();
 133         }
 134         if ( oldTitle !== newTitle ) {
 135                 titleElement.title = newTitle;
 136         }
 137 }
 138
 139 // HTML elements that can have an associated label
 140 // https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Form-associated_content
 141 const labelable = 'button, input, textarea, keygen, meter, output, progress, select';
 142
 143 /**
 144  * Update the title for an element to show the correct access key label.
 145  *
 146  * @private
 147  * @param {HTMLElement} element Element with the accesskey
 148  */
 149 function updateTooltip( element ) {
 150         updateTooltipOnElement( element, element );
 151
 152         // update associated label if there is one
 153         const $element = $( element );
 154         if ( $element.is( labelable ) ) {
 155                 // Search it using 'for' attribute
 156                 const id = element.id.replace( /"/g, '\\"' );
 157                 if ( id ) {
 158                         const $label = $( 'label[for="' + id + '"]' );
 159                         if ( $label.length === 1 ) {
 160                                 updateTooltipOnElement( element, $label[ 0 ] );
 161                         }
 162                 }
 163
 164                 // Search it as parent, because the form control can also be inside the label element itself
 165                 const $labelParent = $element.parents( 'label' );
 166                 if ( $labelParent.length === 1 ) {
 167                         updateTooltipOnElement( element, $labelParent[ 0 ] );
 168                 }
 169         }
 170 }
 171
 172 /**
 173  * Update the titles for all elements in a jQuery selection.
 174  *
 175  * To use this {@link jQuery} plugin, load the `mediawiki.util` module using {@link mw.loader}.
 176  *
 177  * @memberof module:mediawiki.util
 178  * @method
 179  * @return {jQuery}
 180  * @example
 181  * // Converts tooltip "[z]" to associated browser shortcut key e.g. "[ctrl-option-z]"
 182  * mw.loader.using( 'mediawiki.util' ).then( () => {
 183  *     var $a = $('<a href="/wiki/Main_Page" title="Visit the main page [z]" accesskey="z"><span>Main page</span></a>');
 184  *     $a.updateTooltipAccessKeys();
 185  * } );
 186  * @chainable
 187  */
 188 $.fn.updateTooltipAccessKeys = function () {
 189         return this.each( function () {
 190                 updateTooltip( this );
 191         } );
 192 };
 193
 194 $.fn.updateTooltipAccessKeys.getAccessKeyLabel = getAccessKeyLabel;
 195
 196 /**
 197  * getAccessKeyPrefix
 198  *
 199  * @method updateTooltipAccessKeys_getAccessKeyPrefix
 200  * @param {Object} [nav] An object with a 'userAgent' and 'platform' property.
 201  * @return {string}
 202  * @ignore
 203  */
 204 $.fn.updateTooltipAccessKeys.getAccessKeyPrefix = function ( nav ) {
 205         return getAccessKeyModifiers( nav ) + '-';
 206 };
 207
 208 /**
 209  * Switch test mode on and off.
 210  *
 211  * @method updateTooltipAccessKeys_setTestMode
 212  * @param {boolean} mode New mode
 213  * @ignore
 214  */
 215 $.fn.updateTooltipAccessKeys.setTestMode = function ( mode ) {
 216         testMode = mode;
 217 };