WordPress.org

Make WordPress Core

Ticket #42679: 42679.diff

File 42679.diff, 30.1 KB (added by adamsilverstein, 3 years ago)
  • src/wp-admin/js/common.js

    diff --git src/wp-admin/js/common.js src/wp-admin/js/common.js
    index d8748f53af..7c92850a3a 100644
     
    11/* global setUserSetting, ajaxurl, commonL10n, alert, confirm, pagenow */
    22var showNotice, adminMenu, columns, validateForm, screenMeta;
     3
     4/**
     5 *  @summary Adds common WordPress functionality to the window.
     6 *
     7 *  @param {jQuery} $        jQuery object.
     8 *  @param {Object} window   The window object.
     9 *  @param {mixed} undefined Unused.
     10 */
    311( function( $, window, undefined ) {
    412        var $document = $( document ),
    513                $window = $( window ),
    614                $body = $( document.body );
    715
    8 // Removed in 3.3.
    9 // (perhaps) needed for back-compat
     16/**
     17 * @summary Removed in 3.3.0, needed for back-compatibility.
     18 *
     19 * @since 2.7.0
     20 * @deprecated 3.3.0
     21 */
    1022adminMenu = {
    1123        init : function() {},
    1224        fold : function() {},
    adminMenu = { 
    1527        favorites : function() {}
    1628};
    1729
    18 // show/hide/save table columns
     30// Show/hide/save table columns.
    1931columns = {
     32
     33        /**
     34         * @summary Initializes the column toggles in the screen options.
     35         *
     36         * Binds an onClick event to the checkboxes to show or hide the table columns
     37         * based on their toggled state. And persists the toggled state.
     38         *
     39         * @since 2.7.0
     40         *
     41         * @returns {void}
     42         */
    2043        init : function() {
    2144                var that = this;
    2245                $('.hide-column-tog', '#adv-settings').click( function() {
    columns = { 
    3053                });
    3154        },
    3255
     56        /**
     57         * @summary Saves the toggled state for the columns.
     58         *
     59         * Saves whether the columns should be shown or hidden on a page.
     60         *
     61         * @since 3.0.0
     62         *
     63         * @returns {void}
     64         */
    3365        saveManageColumnsState : function() {
    3466                var hidden = this.hidden();
    3567                $.post(ajaxurl, {
    columns = { 
    4072                });
    4173        },
    4274
     75        /**
     76         * @summary Makes a column visible and adjusts the column span for the table.
     77         *
     78         * @since 3.0.0
     79         * @param {string} column The column name.
     80         *
     81         * @returns {void}
     82         */
    4383        checked : function(column) {
    4484                $('.column-' + column).removeClass( 'hidden' );
    4585                this.colSpanChange(+1);
    4686        },
    4787
     88        /**
     89         * @summary Hides a column and adjusts the column span for the table.
     90         *
     91         * @since 3.0.0
     92         * @param {string} column The column name.
     93         *
     94         * @returns {void}
     95         */
    4896        unchecked : function(column) {
    4997                $('.column-' + column).addClass( 'hidden' );
    5098                this.colSpanChange(-1);
    5199        },
    52100
     101        /**
     102         * @summary Get all hidden columns.
     103         *
     104         * @since 3.0.0
     105         *
     106         * @returns {string} The hidden column names separated by a comma.
     107         */
    53108        hidden : function() {
    54109                return $( '.manage-column[id]' ).filter( ':hidden' ).map(function() {
    55110                        return this.id;
    56111                }).get().join( ',' );
    57112        },
    58113
     114        /**
     115         * @summary Gets the checked column toggles from the screen options.
     116         *
     117         * @since 3.0.0
     118         *
     119         * @returns {string} String containing the checked column names.
     120         */
    59121        useCheckboxesForHidden : function() {
    60122                this.hidden = function(){
    61123                        return $('.hide-column-tog').not(':checked').map(function() {
    columns = { 
    65127                };
    66128        },
    67129
     130        /**
     131         * @summary Adjusts the column span for the table.
     132         *
     133         * @since 3.1.0
     134         *
     135         * @param {int} diff The modifier for the column span.
     136         */
    68137        colSpanChange : function(diff) {
    69138                var $t = $('table').find('.colspanchange'), n;
    70139                if ( !$t.length )
    columns = { 
    76145
    77146$document.ready(function(){columns.init();});
    78147
     148/**
     149 * @summary Validates that the required form fields are not empty.
     150 *
     151 * @since 2.9.0
     152 *
     153 * @param {jQuery} form The form to validate.
     154 *
     155 * @returns {boolean} Returns true if all required fields are not an empty string.
     156 */
    79157validateForm = function( form ) {
    80158        return !$( form )
    81159                .find( '.form-required' )
    validateForm = function( form ) { 
    87165};
    88166
    89167// stub for doing better warnings
     168/**
     169 * @summary Shows message pop-up notice or confirmation message.
     170 *
     171 * @since 2.7.0
     172 *
     173 * @type {{warn: showNotice.warn, note: showNotice.note}}
     174 *
     175 * @returns {void}
     176 */
    90177showNotice = {
     178
     179        /**
     180         * @summary Shows a delete confirmation pop-up message.
     181         *
     182         * @since 2.7.0
     183         *
     184         * @returns {boolean} Returns true if the message is confirmed.
     185         */
    91186        warn : function() {
    92187                var msg = commonL10n.warnDelete || '';
    93188                if ( confirm(msg) ) {
    showNotice = { 
    97192                return false;
    98193        },
    99194
     195        /**
     196         * @summary Shows an alert message.
     197         *
     198         * @since 2.7.0
     199         *
     200         * @param text The text to display in the message.
     201         */
    100202        note : function(text) {
    101203                alert(text);
    102204        }
    103205};
    104206
     207/**
     208 * @summary Represents the functions for the meta screen options panel.
     209 *
     210 * @since 3.2.0
     211 *
     212 * @type {{element: null, toggles: null, page: null, init: screenMeta.init,
     213 *         toggleEvent: screenMeta.toggleEvent, open: screenMeta.open,
     214 *         close: screenMeta.close}}
     215 *
     216 * @returns {void}
     217 */
    105218screenMeta = {
    106219        element: null, // #screen-meta
    107220        toggles: null, // .screen-meta-toggle
    108221        page:    null, // #wpcontent
    109222
     223        /**
     224         * @summary Initializes the screen meta options panel.
     225         *
     226         * @since 3.2.0
     227         *
     228         * @returns {void}
     229         */
    110230        init: function() {
    111231                this.element = $('#screen-meta');
    112232                this.toggles = $( '#screen-meta-links' ).find( '.show-settings' );
    screenMeta = { 
    115235                this.toggles.click( this.toggleEvent );
    116236        },
    117237
     238        /**
     239         * @summary Toggles the screen meta options panel.
     240         *
     241         * @since 3.2.0
     242         *
     243         * @returns {void}
     244         */
    118245        toggleEvent: function() {
    119246                var panel = $( '#' + $( this ).attr( 'aria-controls' ) );
    120247
    screenMeta = { 
    127254                        screenMeta.open( panel, $(this) );
    128255        },
    129256
     257        /**
     258         * @summary Opens the screen meta options panel.
     259         *
     260         * @since 3.2.0
     261         *
     262         * @param {jQuery} panel  The screen meta options panel div.
     263         * @param {jQuery} button The toggle button.
     264         *
     265         * @returns {void}
     266         */
    130267        open: function( panel, button ) {
    131268
    132269                $( '#screen-meta-links' ).find( '.screen-meta-toggle' ).not( button.parent() ).css( 'visibility', 'hidden' );
    133270
    134271                panel.parent().show();
     272
     273                /**
     274                 * @summary Sets the focus to the meta options panel and adds the necessary CSS classes.
     275                 *
     276                 * @since 3.2.0
     277                 *
     278                 * @returns {void}
     279                 */
    135280                panel.slideDown( 'fast', function() {
    136281                        panel.focus();
    137282                        button.addClass( 'screen-meta-active' ).attr( 'aria-expanded', true );
    screenMeta = { 
    140285                $document.trigger( 'screen:options:open' );
    141286        },
    142287
     288        /**
     289         * @summary Closes the screen meta options panel.
     290         *
     291         * @since 3.2.0
     292         *
     293         * @param {jQuery} panel  The screen meta options panel div.
     294         * @param {jQuery} button The toggle button.
     295         *
     296         * @returns {void}
     297         */
    143298        close: function( panel, button ) {
     299                /**
     300                 * @summary Hides the screen meta options panel.
     301                 *
     302                 * @since 3.2.0
     303                 *
     304                 * @returns {void}
     305                 */
    144306                panel.slideUp( 'fast', function() {
    145307                        button.removeClass( 'screen-meta-active' ).attr( 'aria-expanded', false );
    146308                        $('.screen-meta-toggle').css('visibility', '');
    screenMeta = { 
    152314};
    153315
    154316/**
    155  * Help tabs.
     317 * @summary Initializes the help tabs in the help panel.
     318 *
     319 * @param {Event} e The event object.
     320 *
     321 * @returns {void}
    156322 */
    157323$('.contextual-help-tabs').delegate('a', 'click', function(e) {
    158324        var link = $(this),
    $('.contextual-help-tabs').delegate('a', 'click', function(e) { 
    178344/**
    179345 * Update custom permalink structure via buttons.
    180346 */
    181 
    182347var permalinkStructureFocused = false,
    183348    $permalinkStructure       = $( '#permalink_structure' ),
    184349    $permalinkStructureInputs = $( '.permalink-structure input:radio' ),
    $document.ready( function() { 
    329494                },
    330495                $headerEnd = $( '.wp-header-end' );
    331496
    332 
    333         // when the menu is folded, make the fly-out submenu header clickable
     497        /**
     498         * @summary Makes the fly-out submenu header clickable, when the menu is folded.
     499         *
     500         * @param {Event} e The event object.
     501         *
     502         * @returns {void}
     503         */
    334504        $adminmenu.on('click.wp-submenu-head', '.wp-submenu-head', function(e){
    335505                $(e.target).parent().siblings('a').get(0).click();
    336506        });
    337507
     508        /**
     509         * @summary Collapses the admin menu.
     510         *
     511         * @returns {void}
     512         */
    338513        $( '#collapse-button' ).on( 'click.collapse-menu', function() {
    339514                var viewportWidth = getViewportWidth() || 961;
    340515
    $document.ready( function() { 
    367542                $document.trigger( 'wp-collapse-menu', { state: menuState } );
    368543        });
    369544
    370         // Handle the `aria-haspopup` attribute on the current menu item when it has a sub-menu.
     545        /**
     546         * @summary Handles the `aria-haspopup` attribute on the current menu item when it has a submenu.
     547         *
     548         * @since 4.4.0
     549         *
     550         * @returns {void}
     551         */
    371552        function currentMenuItemHasPopup() {
    372553                var $current = $( 'a.wp-has-current-submenu' );
    373554
    $document.ready( function() { 
    383564        $document.on( 'wp-menu-state-set wp-collapse-menu wp-responsive-activate wp-responsive-deactivate', currentMenuItemHasPopup );
    384565
    385566        /**
    386          * Ensure an admin submenu is within the visual viewport.
     567         * @summary Ensures an admin submenu is within the visual viewport.
    387568         *
    388569         * @since 4.1.0
    389570         *
    390571         * @param {jQuery} $menuItem The parent menu item containing the submenu.
     572         *
     573         * @returns {void}
    391574         */
    392575        function adjustSubmenu( $menuItem ) {
    393576                var bottomOffset, pageHeight, adjustment, theFold, menutop, wintop, maxtop,
    $document.ready( function() { 
    421604                // iOS Safari works with touchstart, the rest work with click
    422605                mobileEvent = isIOS ? 'touchstart' : 'click';
    423606
    424                 // close any open submenus when touch/click is not on the menu
     607                /**
     608                 * @summary Closes any open submenus when touch/click is not on the menu.
     609                 *
     610                 * @param {Event} e The event object.
     611                 *
     612                 * @returns {void}
     613                 */
    425614                $body.on( mobileEvent+'.wp-mobile-hover', function(e) {
    426615                        if ( $adminmenu.data('wp-responsive') ) {
    427616                                return;
    $document.ready( function() { 
    432621                        }
    433622                });
    434623
     624                /**
     625                 * @summary Handles the opening or closing the submenu based on the mobile click|touch event.
     626                 *
     627                 * @param {Event} event The event object.
     628                 *
     629                 * @returns {void}
     630                 */
    435631                $adminmenu.find( 'a.wp-has-submenu' ).on( mobileEvent + '.wp-mobile-hover', function( event ) {
    436632                        var $menuItem = $(this).parent();
    437633
    $document.ready( function() { 
    453649
    454650        if ( ! isIOS && ! isAndroid ) {
    455651                $adminmenu.find( 'li.wp-has-submenu' ).hoverIntent({
     652
     653                        /**
     654                         * @summary Opens the submenu when hovered over the menu item for desktops.
     655                         *
     656                         * @returns {void}
     657                         */
    456658                        over: function() {
    457659                                var $menuItem = $( this ),
    458660                                        $submenu = $menuItem.find( '.wp-submenu' ),
    $document.ready( function() { 
    471673                                $adminmenu.find( 'li.opensub' ).removeClass( 'opensub' );
    472674                                $menuItem.addClass( 'opensub' );
    473675                        },
     676
     677                        /**
     678                         * @summary Closes the submenu when no longer hovering the menu item.
     679                         *
     680                         * @returns {void}
     681                         */
    474682                        out: function(){
    475683                                if ( $adminmenu.data( 'wp-responsive' ) ) {
    476684                                        // The menu is in responsive mode, bail
    $document.ready( function() { 
    484692                        interval: 90
    485693                });
    486694
     695                /**
     696                 * @summary Opens the submenu on when focused on the menu item.
     697                 *
     698                 * @param {Event} event The event object.
     699                 *
     700                 * @returns {void}
     701                 */
    487702                $adminmenu.on( 'focus.adminmenu', '.wp-submenu a', function( event ) {
    488703                        if ( $adminmenu.data( 'wp-responsive' ) ) {
    489704                                // The menu is in responsive mode, bail
    $document.ready( function() { 
    491706                        }
    492707
    493708                        $( event.target ).closest( 'li.menu-top' ).addClass( 'opensub' );
     709
     710                        /**
     711                         * @summary Closes the submenu on blur from the menu item.
     712                         *
     713                         * @param {Event} event The event object.
     714                         *
     715                         * @returns {void}
     716                         */
    494717                }).on( 'blur.adminmenu', '.wp-submenu a', function( event ) {
    495718                        if ( $adminmenu.data( 'wp-responsive' ) ) {
    496719                                return;
    497720                        }
    498721
    499722                        $( event.target ).closest( 'li.menu-top' ).removeClass( 'opensub' );
     723
     724                        /**
     725                         * @summary Adjusts the size for the submenu.
     726                         *
     727                         * @returns {void}
     728                         */
    500729                }).find( 'li.wp-has-submenu.wp-not-current-submenu' ).on( 'focusin.adminmenu', function() {
    501730                        adjustSubmenu( $( this ) );
    502731                });
    $document.ready( function() { 
    513742        }
    514743        $( 'div.updated, div.error, div.notice' ).not( '.inline, .below-h2' ).insertAfter( $headerEnd );
    515744
    516         // Make notices dismissible
     745        /**
     746         * @summary Make notices dismissible.
     747         *
     748         * @since 4.4.0
     749         *
     750         * @returns {void}
     751         */
    517752        function makeNoticesDismissible() {
    518753                $( '.notice.is-dismissible' ).each( function() {
    519754                        var $el = $( this ),
    $document.ready( function() { 
    540775        // Init screen meta
    541776        screenMeta.init();
    542777
    543         // This event needs to be delegated. Ticket #37973.
     778        /**
     779         * @summary Checks a checkbox.
     780         *
     781         * This event needs to be delegated. Ticket #37973.
     782         *
     783         * @returns {boolean} Returns whether a checkbox is checked or not.
     784         */
    544785        $body.on( 'click', 'tbody > tr > .check-column :checkbox', function( event ) {
    545786                // Shift click to select a range of checkboxes.
    546787                if ( 'undefined' == event.shiftKey ) { return true; }
    $document.ready( function() { 
    564805
    565806                // Toggle the "Select all" checkboxes depending if the other ones are all checked or not.
    566807                var unchecked = $(this).closest('tbody').find(':checkbox').filter(':visible:enabled').not(':checked');
     808
     809                /**
     810                 * @summary Determines if all checkboxes are checked.
     811                 *
     812                 * @returns {boolean} Returns true if there are no unchecked checkboxes.
     813                 */
    567814                $(this).closest('table').children('thead, tfoot').find(':checkbox').prop('checked', function() {
    568815                        return ( 0 === unchecked.length );
    569816                });
    $document.ready( function() { 
    571818                return true;
    572819        });
    573820
    574         // This event needs to be delegated. Ticket #37973.
     821        /**
     822         * @summary Controls all the toggles on bulk toggle change.
     823         *
     824         * When the bulk checkbox is changed, all the checkboxes in the tables are changed accordingly.
     825         * When the shift-button is pressed while changing the bulk checkbox the checkboxes in the table are inverted.
     826         *
     827         * This event needs to be delegated. Ticket #37973.
     828         *
     829         * @param {Event} event The event object.
     830         *
     831         * @returns {boolean}
     832         */
    575833        $body.on( 'click.wp-toggle-checkboxes', 'thead .check-column :checkbox, tfoot .check-column :checkbox', function( event ) {
    576834                var $this = $(this),
    577835                        $table = $this.closest( 'table' ),
    $document.ready( function() { 
    580838
    581839                $table.children( 'tbody' ).filter(':visible')
    582840                        .children().children('.check-column').find(':checkbox')
     841                        /**
     842                         * @summary Updates the checked state on the checkbox in the table.
     843                         *
     844                         * @returns {boolean} True checks the checkbox, False unchecks the checkbox.
     845                         */
    583846                        .prop('checked', function() {
    584847                                if ( $(this).is(':hidden,:disabled') ) {
    585848                                        return false;
    $document.ready( function() { 
    596859
    597860                $table.children('thead,  tfoot').filter(':visible')
    598861                        .children().children('.check-column').find(':checkbox')
     862
     863                        /**
     864                         * @summary Syncs the bulk checkboxes on the top and bottom of the table.
     865                         *
     866                         * @returns {boolean} True checks the checkbox, False unchecks the checkbox.
     867                         */
    599868                        .prop('checked', function() {
    600869                                if ( toggle ) {
    601870                                        return false;
    $document.ready( function() { 
    607876                        });
    608877        });
    609878
    610         // Show row actions on keyboard focus of its parent container element or any other elements contained within
     879        /**
     880         * @summary Shows row actions on focus of its parent container element or any other elements contained within.
     881         *
     882         * @returns {void}
     883         */
    611884        $( '#wpbody-content' ).on({
    612885                focusin: function() {
    613886                        clearTimeout( transitionTimeout );
    $document.ready( function() { 
    636909                return false;
    637910        });
    638911
    639         // tab in textareas
     912        /**
     913         * @summary Handles tab keypresses in theme and plugin editor textareas.
     914         *
     915         * @param {Event} e The event object.
     916         *
     917         * @returns {void}
     918         */
    640919        $('#newcontent').bind('keydown.wpevent_InsertTab', function(e) {
    641920                var el = e.target, selStart, selEnd, val, scroll, sel;
    642921
    643                 if ( e.keyCode == 27 ) { // escape key
     922                // After pressing escape key (keyCode: 27), the tab key should tab out of the textarea.
     923                if ( e.keyCode == 27 ) {
    644924                        // when pressing Escape: Opera 12 and 27 blur form fields, IE 8 clears them
    645925                        e.preventDefault();
    646926                        $(el).data('tab-out', true);
    647927                        return;
    648928                }
    649929
    650                 if ( e.keyCode != 9 || e.ctrlKey || e.altKey || e.shiftKey ) // tab key
     930                // Only listen for plain tab key (keyCode: 9) without any modifiers.
     931                if ( e.keyCode != 9 || e.ctrlKey || e.altKey || e.shiftKey )
    651932                        return;
    652933
     934                // After tabbing out, reset it so next time the tab key can be used again.
    653935                if ( $(el).data('tab-out') ) {
    654936                        $(el).data('tab-out', false);
    655937                        return;
    $document.ready( function() { 
    659941                selEnd = el.selectionEnd;
    660942                val = el.value;
    661943
     944                // If any text is selected, replace the selection with a tab character.
    662945                if ( document.selection ) {
    663946                        el.focus();
    664947                        sel = document.selection.createRange();
    $document.ready( function() { 
    670953                        this.scrollTop = scroll;
    671954                }
    672955
     956                // Cancel the regular tab functionality, to prevent losing focus of the textarea.
    673957                if ( e.stopPropagation )
    674958                        e.stopPropagation();
    675959                if ( e.preventDefault )
    676960                        e.preventDefault();
    677961        });
    678962
     963        // Reset page number variable for new filters/searches but not for bulk actions. See #17685.
    679964        if ( pageInput.length ) {
    680                 pageInput.closest('form').submit( function() {
    681965
    682                         // Reset paging var for new filters/searches but not for bulk actions. See #17685.
     966                /**
     967                 * @summary Handles pagination variable when filtering the list table.
     968                 *
     969                 * Set the pagination argument to the first page when the post-filter form is submitted.
     970                 * This happens when pressing the 'filter' button on the list table page.
     971                 *
     972                 * The pagination argument should not be touched when the bulk action dropdowns are set to do anything.
     973                 *
     974                 * The form closest to the pageInput is the post-filter form.
     975                 *
     976                 * @returns {void}
     977                 */
     978                pageInput.closest('form').submit( function() {
     979                        /*
     980                         * action = bulk action dropdown at the top of the table
     981                         * action2 = bulk action dropdow at the bottom of the table
     982                         */
    683983                        if ( $('select[name="action"]').val() == -1 && $('select[name="action2"]').val() == -1 && pageInput.val() == currentPage )
    684984                                pageInput.val('1');
    685985                });
    686986        }
    687987
     988        /**
     989         * @summary Resets the bulk actions when the search button is clicked.
     990         *
     991         * @returns {void}
     992         */
    688993        $('.search-box input[type="search"], .search-box input[type="submit"]').mousedown(function () {
    689994                $('select[name^="action"]').val('-1');
    690995        });
    691996
    692         // Scroll into view when focused
     997        /**
     998         * @summary Scrolls into view when focus.scroll-into-view is triggered.
     999         *
     1000         * @param {Event} e The event object.
     1001         *
     1002         * @returns {void}
     1003         */
    6931004        $('#contextual-help-link, #show-settings-link').on( 'focus.scroll-into-view', function(e){
    6941005                if ( e.target.scrollIntoView )
    6951006                        e.target.scrollIntoView(false);
    6961007        });
    6971008
    698         // Disable upload buttons until files are selected
     1009        /**
     1010         * @summary Disables the submit upload buttons when no data is entered.
     1011         *
     1012         * @returns {void}
     1013         */
    6991014        (function(){
    7001015                var button, input, form = $('form.wp-upload-form');
     1016
     1017                // Exit when no upload form is found.
    7011018                if ( ! form.length )
    7021019                        return;
     1020
    7031021                button = form.find('input[type="submit"]');
    7041022                input = form.find('input[type="file"]');
    7051023
     1024                /**
     1025                 * @summary Determines if any data is entered in any file upload input.
     1026                 *
     1027                 * @since 3.5.0
     1028                 *
     1029                 * @returns {void}
     1030                 */
    7061031                function toggleUploadButton() {
     1032                        // When no inputs have a value, disable the upload buttons.
    7071033                        button.prop('disabled', '' === input.map( function() {
    7081034                                return $(this).val();
    7091035                        }).get().join(''));
    7101036                }
     1037
     1038                // Update the status initially.
    7111039                toggleUploadButton();
     1040                // Update the status when any file input changes.
    7121041                input.on('change', toggleUploadButton);
    7131042        })();
    7141043
     1044        /**
     1045         * @summary Pins the menu while distraction-free writing is enabled.
     1046         *
     1047         * @param {Event} event Event data.
     1048         *
     1049         * @since 4.1.0
     1050         *
     1051         * @returns {void}
     1052         */
    7151053        function pinMenu( event ) {
    7161054                var windowPos = $window.scrollTop(),
    7171055                        resizing = ! event || event.type !== 'scroll';
    $document.ready( function() { 
    7201058                        return;
    7211059                }
    7221060
     1061                /*
     1062                 * When the menu is higher than the window and smaller than the entire page.
     1063                 * It should be adjusted to be able to see the entire menu.
     1064                 *
     1065                 * Otherwise it can be accessed normally.
     1066                 */
    7231067                if ( height.menu + height.adminbar < height.window ||
    7241068                        height.menu + height.adminbar + 20 > height.wpwrap ) {
    7251069                        unpinMenu();
    $document.ready( function() { 
    7281072
    7291073                menuIsPinned = true;
    7301074
     1075                // If the menu is higher than the window, compensate on scroll.
    7311076                if ( height.menu + height.adminbar > height.window ) {
    732                         // Check for overscrolling
     1077                        // Check for overscrolling, this happens when swiping up at the top of the document in modern browsers.
    7331078                        if ( windowPos < 0 ) {
     1079                                // Stick the menu to the top.
    7341080                                if ( ! pinnedMenuTop ) {
    7351081                                        pinnedMenuTop = true;
    7361082                                        pinnedMenuBottom = false;
    $document.ready( function() { 
    7441090
    7451091                                return;
    7461092                        } else if ( windowPos + height.window > $document.height() - 1 ) {
     1093                                // When overscrolling at the bottom, stick the menu to the bottom.
    7471094                                if ( ! pinnedMenuBottom ) {
    7481095                                        pinnedMenuBottom = true;
    7491096                                        pinnedMenuTop = false;
    $document.ready( function() { 
    7591106                        }
    7601107
    7611108                        if ( windowPos > lastScrollPosition ) {
    762                                 // Scrolling down
     1109                                // When a down scroll has been detected.
     1110
     1111                                // If it was pinned to the top, unpin and calculate relative scroll.
    7631112                                if ( pinnedMenuTop ) {
    764                                         // let it scroll
    7651113                                        pinnedMenuTop = false;
     1114                                        // Calculate new offset position.
    7661115                                        menuTop = $adminMenuWrap.offset().top - height.adminbar - ( windowPos - lastScrollPosition );
    7671116
    7681117                                        if ( menuTop + height.menu + height.adminbar < windowPos + height.window ) {
    $document.ready( function() { 
    7751124                                                bottom: ''
    7761125                                        });
    7771126                                } else if ( ! pinnedMenuBottom && $adminMenuWrap.offset().top + height.menu < windowPos + height.window ) {
    778                                         // pin the bottom
     1127                                        // Pin it to the bottom.
    7791128                                        pinnedMenuBottom = true;
    7801129
    7811130                                        $adminMenuWrap.css({
    $document.ready( function() { 
    7851134                                        });
    7861135                                }
    7871136                        } else if ( windowPos < lastScrollPosition ) {
    788                                 // Scrolling up
     1137                                // When a scroll up is detected.
     1138
     1139                                // If it was pinned to the bottom, unpin and calculate relative scroll.
    7891140                                if ( pinnedMenuBottom ) {
    790                                         // let it scroll
    7911141                                        pinnedMenuBottom = false;
     1142
     1143                                        // Calculate new offset position.
    7921144                                        menuTop = $adminMenuWrap.offset().top - height.adminbar + ( lastScrollPosition - windowPos );
    7931145
    7941146                                        if ( menuTop + height.menu > windowPos + height.window ) {
    $document.ready( function() { 
    8011153                                                bottom: ''
    8021154                                        });
    8031155                                } else if ( ! pinnedMenuTop && $adminMenuWrap.offset().top >= windowPos + height.adminbar ) {
    804                                         // pin the top
     1156
     1157                                        // Pin it to the top.
    8051158                                        pinnedMenuTop = true;
    8061159
    8071160                                        $adminMenuWrap.css({
    $document.ready( function() { 
    8111164                                        });
    8121165                                }
    8131166                        } else if ( resizing ) {
    814                                 // Resizing
     1167                                // Window is being resized.
     1168
    8151169                                pinnedMenuTop = pinnedMenuBottom = false;
     1170
     1171                                // Calculate the new offset.
    8161172                                menuTop = windowPos + height.window - height.menu - height.adminbar - 1;
    8171173
    8181174                                if ( menuTop > 0 ) {
    $document.ready( function() { 
    8301186                lastScrollPosition = windowPos;
    8311187        }
    8321188
     1189        /**
     1190         * @summary Determines the height of certain elements.
     1191         *
     1192         * @since 4.1.0
     1193         *
     1194         * @returns {void}
     1195         */
    8331196        function resetHeights() {
    8341197                height = {
    8351198                        window: $window.height(),
    $document.ready( function() { 
    8391202                };
    8401203        }
    8411204
     1205        /**
     1206         * @summary Unpins the menu.
     1207         *
     1208         * @since 4.1.0
     1209         *
     1210         * @returns {void}
     1211         */
    8421212        function unpinMenu() {
    8431213                if ( isIOS || ! menuIsPinned ) {
    8441214                        return;
    $document.ready( function() { 
    8521222                });
    8531223        }
    8541224
     1225        /**
     1226         * @summary Pins and unpins the menu when applicable.
     1227         *
     1228         * @since 4.1.0
     1229         *
     1230         * @returns {void}
     1231         */
    8551232        function setPinMenu() {
    8561233                resetHeights();
    8571234
    $document.ready( function() { 
    8741251                });
    8751252        }
    8761253
     1254        /**
     1255         * @summary Changes properties of metaboxes and body.
     1256         *
     1257         * Changes the sortables and responsiveness of metaboxes.
     1258         *
     1259         * @since 3.8.0
     1260         *
     1261         *@returns {void}
     1262         */
    8771263        window.wpResponsive = {
     1264
     1265                /**
     1266                 * @summary Initializes the wpResponsive object.
     1267                 *
     1268                 * @since 3.8.0
     1269                 *
     1270                 * @returns {void}
     1271                 */
    8781272                init: function() {
    8791273                        var self = this;
    8801274
    $document.ready( function() { 
    8871281
    8881282                        $( '#wp-admin-bar-menu-toggle a' ).attr( 'aria-expanded', 'false' );
    8891283
    890                         // Toggle sidebar when toggle is clicked
     1284                        // Toggle sidebar when toggle is clicked.
    8911285                        $( '#wp-admin-bar-menu-toggle' ).on( 'click.wp-responsive', function( event ) {
    8921286                                event.preventDefault();
    8931287
    894                                 // close any open toolbar submenus
     1288                                // close any open toolbar submenus.
    8951289                                $adminbar.find( '.hover' ).removeClass( 'hover' );
    8961290
    8971291                                $wpwrap.toggleClass( 'wp-responsive-open' );
    $document.ready( function() { 
    9031297                                }
    9041298                        } );
    9051299
    906                         // Add menu events
     1300                        // Add menu events.
    9071301                        $adminmenu.on( 'click.wp-responsive', 'li.wp-has-submenu > a', function( event ) {
    9081302                                if ( ! $adminmenu.data('wp-responsive') ) {
    9091303                                        return;
    $document.ready( function() { 
    9161310                        self.trigger();
    9171311                        $document.on( 'wp-window-resized.wp-responsive', $.proxy( this.trigger, this ) );
    9181312
    919                         // This needs to run later as UI Sortable may be initialized later on $(document).ready()
     1313                        // This needs to run later as UI Sortable may be initialized later on $(document).ready().
    9201314                        $window.on( 'load.wp-responsive', function() {
    9211315                                var width = navigator.userAgent.indexOf('AppleWebKit/') > -1 ? $window.width() : window.innerWidth;
    9221316
    $document.ready( function() { 
    9261320                        });
    9271321                },
    9281322
     1323                /**
     1324                 * @summary Changes properties of body and admin menu.
     1325                 *
     1326                 * Pins and unpins the menu and adds the auto-fold class to the body.
     1327                 * Makes the admin menu responsive and disables the metabox sortables.
     1328                 *
     1329                 * @since 3.8.0
     1330                 *
     1331                 * @returns {void}
     1332                 */
    9291333                activate: function() {
    9301334                        setPinMenu();
    9311335
    932                         if ( ! $body.hasClass( 'auto-fold' ) ) {
    933                                 $body.addClass( 'auto-fold' );
     1336                        if ( ! $body.hasClass( "auto-fold" ) ) {
     1337                                $body.addClass( "auto-fold" );
    9341338                        }
    9351339
    936                         $adminmenu.data( 'wp-responsive', 1 );
     1340                        $adminmenu.data( "wp-responsive", 1 );
    9371341                        this.disableSortables();
    9381342                },
    9391343
     1344                /**
     1345                 * @summary Changes properties of admin menu and enables metabox sortables.
     1346                 *
     1347                 * Pin and unpin the menu.
     1348                 * Removes the responsiveness of the admin menu and enables the metabox sortables.
     1349                 *
     1350                 * @since 3.8.0
     1351                 *
     1352                 * @returns {void}
     1353                 */
    9401354                deactivate: function() {
    9411355                        setPinMenu();
    9421356                        $adminmenu.removeData('wp-responsive');
    9431357                        this.enableSortables();
    9441358                },
    9451359
     1360                /**
     1361                 * @summary Sets the responsiveness and enables the overlay based on the viewport width.
     1362                 *
     1363                 * @since 3.8.0
     1364                 *
     1365                 * @returns {void}
     1366                 */
    9461367                trigger: function() {
    9471368                        var viewportWidth = getViewportWidth();
    9481369
    $document.ready( function() { 
    9531374
    9541375                        if ( viewportWidth <= 782 ) {
    9551376                                if ( ! wpResponsiveActive ) {
    956                                         $document.trigger( 'wp-responsive-activate' );
     1377                                        $document.trigger( "wp-responsive-activate" );
    9571378                                        wpResponsiveActive = true;
    9581379                                }
    9591380                        } else {
    9601381                                if ( wpResponsiveActive ) {
    961                                         $document.trigger( 'wp-responsive-deactivate' );
     1382                                        $document.trigger( "wp-responsive-deactivate" );
    9621383                                        wpResponsiveActive = false;
    9631384                                }
    9641385                        }
    $document.ready( function() { 
    9701391                        }
    9711392                },
    9721393
     1394                /**
     1395                 * @summary Inserts a responsive overlay and toggles the window.
     1396                 *
     1397                 * @since 3.8.0
     1398                 *
     1399                 * @returns {void}
     1400                 */
    9731401                enableOverlay: function() {
    9741402                        if ( $overlay.length === 0 ) {
    9751403                                $overlay = $( '<div id="wp-responsive-overlay"></div>' )
    $document.ready( function() { 
    9861414                        });
    9871415                },
    9881416
     1417                /**
     1418                 * @summary Disables the responsive overlay and removes the overlay.
     1419                 *
     1420                 * @since 3.8.0
     1421                 *
     1422                 * @returns {void}
     1423                 */
    9891424                disableOverlay: function() {
    990                         $toolbarPopups.off( 'click.wp-responsive' );
     1425                        $toolbarPopups.off( "click.wp-responsive" );
    9911426                        $overlay.hide();
    9921427                },
    9931428
     1429                /**
     1430                 * @summary Disables sortables.
     1431                 *
     1432                 * @since 3.8.0
     1433                 *
     1434                 * @returns {void}
     1435                 */
    9941436                disableSortables: function() {
    9951437                        if ( $sortables.length ) {
    9961438                                try {
    997                                         $sortables.sortable('disable');
    998                                 } catch(e) {}
     1439                                        $sortables.sortable( "disable" );
     1440                                } catch ( e ) {}
    9991441                        }
    10001442                },
    10011443
     1444                /**
     1445                 * @summary Enables sortables.
     1446                 *
     1447                 * @since 3.8.0
     1448                 *
     1449                 * @returns {void}
     1450                 */
    10021451                enableSortables: function() {
    10031452                        if ( $sortables.length ) {
    10041453                                try {
    1005                                         $sortables.sortable('enable');
    1006                                 } catch(e) {}
     1454                                        $sortables.sortable( "enable" );
     1455                                } catch ( e ) {}
    10071456                        }
    10081457                }
    10091458        };
    10101459
    1011         // Add an ARIA role `button` to elements that behave like UI controls when JavaScript is on.
     1460        /**
     1461         * @summary Add an ARIA role `button` to elements that behave like UI controls when JavaScript is on.
     1462         *
     1463         * @since 4.5.0
     1464         *
     1465         * @returns {void}
     1466         */
    10121467        function aria_button_if_js() {
    1013                 $( '.aria-button-if-js' ).attr( 'role', 'button' );
     1468                $( ".aria-button-if-js" ).attr( "role", "button" );
    10141469        }
    10151470
    10161471        $( document ).ajaxComplete( function() {
    $document.ready( function() { 
    10371492        }
    10381493
    10391494        /**
    1040          * @summary Set the admin menu collapsed/expanded state.
     1495         * @summary Sets the admin menu collapsed/expanded state.
    10411496         *
    10421497         * Sets the global variable `menuState` and triggers a custom event passing
    10431498         * the current menu state.
    $document.ready( function() { 
    10641519        $document.on( 'wp-window-resized.set-menu-state', setMenuState );
    10651520
    10661521        /**
    1067          * @summary Set ARIA attributes on the collapse/expand menu button.
     1522         * @summary Sets ARIA attributes on the collapse/expand menu button.
    10681523         *
    10691524         * When the admin menu is open or folded, updates the `aria-expanded` and
    10701525         * `aria-label` attributes of the button to give feedback to assistive
    $document.ready( function() { 
    11221577        });
    11231578});
    11241579
    1125 // Fire a custom jQuery event at the end of window resize
     1580// Fire a custom jQuery event at the end of window resize.
    11261581( function() {
    11271582        var timeout;
    11281583
     1584        /**
     1585         * @summary Triggers the WP window-resize event.
     1586         *
     1587         * @since 3.8.0
     1588         *
     1589         * @returns {void}
     1590         */
    11291591        function triggerEvent() {
    1130                 $document.trigger( 'wp-window-resized' );
     1592                $document.trigger( "wp-window-resized" );
    11311593        }
    11321594
     1595        /**
     1596         * @summary Fires the trigger event again after 200 ms.
     1597         *
     1598         * @since 3.8.0
     1599         *
     1600         * @returns {void}
     1601         */
    11331602        function fireOnce() {
    11341603                window.clearTimeout( timeout );
    11351604                timeout = window.setTimeout( triggerEvent, 200 );