1 files changed, 129 insertions, 44 deletions

diff --git a/core/misc/tableselect.js b/core/misc/tableselect.js
index 4d8712ae308..785198a5d9b 100644
--- a/core/misc/tableselect.js
+++ b/core/misc/tableselect.js
@@ -1,92 +1,177 @@
 /**
-* DO NOT EDIT THIS FILE.
-* See the following change record for more information,
-* https://www.drupal.org/node/2815083
-* @preserve
-**/
+ * @file
+ * Table select functionality.
+ */
 
 (function ($, Drupal) {
+  /**
+   * Initialize tableSelects.
+   *
+   * @type {Drupal~behavior}
+   *
+   * @prop {Drupal~behaviorAttach} attach
+   *   Attaches tableSelect functionality.
+   */
   Drupal.behaviors.tableSelect = {
     attach(context, settings) {
-      once('table-select', $(context).find('th.select-all').closest('table')).forEach(table => Drupal.tableSelect.call(table));
-    }
-
+      // Select the inner-most table in case of nested tables.
+      once(
+        'table-select',
+        $(context).find('th.select-all').closest('table'),
+      ).forEach((table) => Drupal.tableSelect.call(table));
+    },
   };
 
+  /**
+   * Callback used in {@link Drupal.behaviors.tableSelect}.
+   */
   Drupal.tableSelect = function () {
+    // Do not add a "Select all" checkbox if there are no rows with checkboxes
+    // in the table.
     if ($(this).find('td input[type="checkbox"]').length === 0) {
       return;
     }
 
+    // Keep track of the table, which checkbox is checked and alias the
+    // settings.
     const table = this;
     let checkboxes;
     let lastChecked;
     const $table = $(table);
     const strings = {
       selectAll: Drupal.t('Select all rows in this table'),
-      selectNone: Drupal.t('Deselect all rows in this table')
+      selectNone: Drupal.t('Deselect all rows in this table'),
     };
-
     const updateSelectAll = function (state) {
-      $table.prev('table.sticky-header').addBack().find('th.select-all input[type="checkbox"]').each(function () {
-        const $checkbox = $(this);
-        const stateChanged = $checkbox.prop('checked') !== state;
-        $checkbox.attr('title', state ? strings.selectNone : strings.selectAll);
-
-        if (stateChanged) {
-          $checkbox.prop('checked', state).trigger('change');
-        }
-      });
-    };
-
-    $table.find('th.select-all').prepend($(Drupal.theme('checkbox')).attr('title', strings.selectAll)).on('click', event => {
-      if ($(event.target).is('input[type="checkbox"]')) {
-        checkboxes.each(function () {
+      // Update table's select-all checkbox (and sticky header's if available).
+      $table
+        .prev('table.sticky-header')
+        .addBack()
+        .find('th.select-all input[type="checkbox"]')
+        .each(function () {
           const $checkbox = $(this);
-          const stateChanged = $checkbox.prop('checked') !== event.target.checked;
+          const stateChanged = $checkbox.prop('checked') !== state;
+
+          $checkbox.attr(
+            'title',
+            state ? strings.selectNone : strings.selectAll,
+          );
 
+          /**
+           * @checkbox {HTMLElement}
+           */
           if (stateChanged) {
-            $checkbox.prop('checked', event.target.checked).trigger('change');
+            $checkbox.prop('checked', state).trigger('change');
           }
-
-          $checkbox.closest('tr').toggleClass('selected', this.checked);
         });
-        updateSelectAll(event.target.checked);
-      }
-    });
-    checkboxes = $table.find('td input[type="checkbox"]:enabled').on('click', function (e) {
-      $(this).closest('tr').toggleClass('selected', this.checked);
+    };
 
-      if (e.shiftKey && lastChecked && lastChecked !== e.target) {
-        Drupal.tableSelectRange($(e.target).closest('tr')[0], $(lastChecked).closest('tr')[0], e.target.checked);
-      }
+    // Find all <th> with class select-all, and insert the check all checkbox.
+    $table
+      .find('th.select-all')
+      .prepend($(Drupal.theme('checkbox')).attr('title', strings.selectAll))
+      .on('click', (event) => {
+        if ($(event.target).is('input[type="checkbox"]')) {
+          // Loop through all checkboxes and set their state to the select all
+          // checkbox' state.
+          checkboxes.each(function () {
+            const $checkbox = $(this);
+            const stateChanged =
+              $checkbox.prop('checked') !== event.target.checked;
+
+            /**
+             * @checkbox {HTMLElement}
+             */
+            if (stateChanged) {
+              $checkbox.prop('checked', event.target.checked).trigger('change');
+            }
+            // Either add or remove the selected class based on the state of the
+            // check all checkbox.
+
+            /**
+             * @checkbox {HTMLElement}
+             */
+            $checkbox.closest('tr').toggleClass('selected', this.checked);
+          });
+          // Update the title and the state of the check all box.
+          updateSelectAll(event.target.checked);
+        }
+      });
+
+    // For each of the checkboxes within the table that are not disabled.
+    checkboxes = $table
+      .find('td input[type="checkbox"]:enabled')
+      .on('click', function (e) {
+        // Either add or remove the selected class based on the state of the
+        // check all checkbox.
+
+        /**
+         * @this {HTMLElement}
+         */
+        $(this).closest('tr').toggleClass('selected', this.checked);
+
+        // If this is a shift click, we need to highlight everything in the
+        // range. Also make sure that we are actually checking checkboxes
+        // over a range and that a checkbox has been checked or unchecked before.
+        if (e.shiftKey && lastChecked && lastChecked !== e.target) {
+          // We use the checkbox's parent <tr> to do our range searching.
+          Drupal.tableSelectRange(
+            $(e.target).closest('tr')[0],
+            $(lastChecked).closest('tr')[0],
+            e.target.checked,
+          );
+        }
+
+        // If all checkboxes are checked, make sure the select-all one is checked
+        // too, otherwise keep unchecked.
+        updateSelectAll(
+          checkboxes.length === checkboxes.filter(':checked').length,
+        );
 
-      updateSelectAll(checkboxes.length === checkboxes.filter(':checked').length);
-      lastChecked = e.target;
-    });
+        // Keep track of the last checked checkbox.
+        lastChecked = e.target;
+      });
+
+    // If all checkboxes are checked on page load, make sure the select-all one
+    // is checked too, otherwise keep unchecked.
     updateSelectAll(checkboxes.length === checkboxes.filter(':checked').length);
   };
 
+  /**
+   * @param {HTMLElement} from
+   *   The HTML element representing the "from" part of the range.
+   * @param {HTMLElement} to
+   *   The HTML element representing the "to" part of the range.
+   * @param {bool} state
+   *   The state to set on the range.
+   */
   Drupal.tableSelectRange = function (from, to, state) {
-    const mode = from.rowIndex > to.rowIndex ? 'previousSibling' : 'nextSibling';
+    // We determine the looping mode based on the order of from and to.
+    const mode =
+      from.rowIndex > to.rowIndex ? 'previousSibling' : 'nextSibling';
 
+    // Traverse through the sibling nodes.
     for (let i = from[mode]; i; i = i[mode]) {
       const $i = $(i);
-
+      // Make sure that we're only dealing with elements.
       if (i.nodeType !== 1) {
         continue;
       }
-
+      // Either add or remove the selected class based on the state of the
+      // target checkbox.
       $i.toggleClass('selected', state);
       $i.find('input[type="checkbox"]').prop('checked', state);
 
       if (to.nodeType) {
+        // If we are at the end of the range, stop.
         if (i === to) {
           break;
         }
-      } else if ($.filter(to, [i]).r.length) {
+      }
+      // A faster alternative to doing $(i).filter(to).length.
+      else if ($.filter(to, [i]).r.length) {
         break;
       }
     }
   };
-})(jQuery, Drupal);
\ No newline at end of file
+})(jQuery, Drupal);