Issue #3278415 by nod_, lauriii, catch, Wim Leers, longwave, xjm, claudiu.cristea: Remove usages of the JavaScript ES6 build step, the build step itself, and associated dev dependencies

1 files changed, 215 insertions, 48 deletions

diff --git a/core/misc/form.js b/core/misc/form.js
index ea5f8f50e60..c02220c0997 100644
--- a/core/misc/form.js
+++ b/core/misc/form.js
@@ -1,39 +1,125 @@
 /**
-* DO NOT EDIT THIS FILE.
-* See the following change record for more information,
-* https://www.drupal.org/node/2815083
-* @preserve
-**/
+ * @file
+ * Form features.
+ */
+
+/**
+ * Triggers when a value in the form changed.
+ *
+ * The event triggers when content is typed or pasted in a text field, before
+ * the change event triggers.
+ *
+ * @event formUpdated
+ */
+
+/**
+ * Triggers when a click on a page fragment link or hash change is detected.
+ *
+ * The event triggers when the fragment in the URL changes (a hash change) and
+ * when a link containing a fragment identifier is clicked. In case the hash
+ * changes due to a click this event will only be triggered once.
+ *
+ * @event formFragmentLinkClickOrHashChange
+ */
 
 (function ($, Drupal, debounce) {
+  /**
+   * Retrieves the summary for the first element.
+   *
+   * @return {string}
+   *   The text of the summary.
+   */
   $.fn.drupalGetSummary = function () {
     const callback = this.data('summaryCallback');
     return this[0] && callback ? callback(this[0]).trim() : '';
   };
 
+  /**
+   * Sets the summary for all matched elements.
+   *
+   * @param {function} callback
+   *   Either a function that will be called each time the summary is
+   *   retrieved or a string (which is returned each time).
+   *
+   * @return {jQuery}
+   *   jQuery collection of the current element.
+   *
+   * @fires event:summaryUpdated
+   *
+   * @listens event:formUpdated
+   */
   $.fn.drupalSetSummary = function (callback) {
     const self = this;
 
+    // To facilitate things, the callback should always be a function. If it's
+    // not, we wrap it into an anonymous function which just returns the value.
     if (typeof callback !== 'function') {
       const val = callback;
-
       callback = function () {
         return val;
       };
     }
 
-    return this.data('summaryCallback', callback).off('formUpdated.summary').on('formUpdated.summary', () => {
-      self.trigger('summaryUpdated');
-    }).trigger('summaryUpdated');
+    return (
+      this.data('summaryCallback', callback)
+        // To prevent duplicate events, the handlers are first removed and then
+        // (re-)added.
+        .off('formUpdated.summary')
+        .on('formUpdated.summary', () => {
+          self.trigger('summaryUpdated');
+        })
+        // The actual summaryUpdated handler doesn't fire when the callback is
+        // changed, so we have to do this manually.
+        .trigger('summaryUpdated')
+    );
   };
 
+  /**
+   * Prevents consecutive form submissions of identical form values.
+   *
+   * Repetitive form submissions that would submit the identical form values
+   * are prevented, unless the form values are different to the previously
+   * submitted values.
+   *
+   * This is a simplified re-implementation of a user-agent behavior that
+   * should be natively supported by major web browsers, but at this time, only
+   * Firefox has a built-in protection.
+   *
+   * A form value-based approach ensures that the constraint is triggered for
+   * consecutive, identical form submissions only. Compared to that, a form
+   * button-based approach would (1) rely on [visible] buttons to exist where
+   * technically not required and (2) require more complex state management if
+   * there are multiple buttons in a form.
+   *
+   * This implementation is based on form-level submit events only and relies
+   * on jQuery's serialize() method to determine submitted form values. As such,
+   * the following limitations exist:
+   *
+   * - Event handlers on form buttons that preventDefault() do not receive a
+   *   double-submit protection. That is deemed to be fine, since such button
+   *   events typically trigger reversible client-side or server-side
+   *   operations that are local to the context of a form only.
+   * - Changed values in advanced form controls, such as file inputs, are not
+   *   part of the form values being compared between consecutive form submits
+   *   (due to limitations of jQuery.serialize()). That is deemed to be
+   *   acceptable, because if the user forgot to attach a file, then the size of
+   *   HTTP payload will most likely be small enough to be fully passed to the
+   *   server endpoint within (milli)seconds. If a user mistakenly attached a
+   *   wrong file and is technically versed enough to cancel the form submission
+   *   (and HTTP payload) in order to attach a different file, then that
+   *   edge-case is not supported here.
+   *
+   * Lastly, all forms submitted via HTTP GET are idempotent by definition of
+   * HTTP standards, so excluded in this implementation.
+   *
+   * @type {Drupal~behavior}
+   */
   Drupal.behaviors.formSingleSubmit = {
     attach() {
       function onFormSubmit(e) {
         const $form = $(e.currentTarget);
         const formValues = $form.serialize();
         const previousValues = $form.attr('data-drupal-form-submit-last');
-
         if (previousValues === formValues) {
           e.preventDefault();
         } else {
@@ -41,78 +127,130 @@
         }
       }
 
-      $(once('form-single-submit', 'body')).on('submit.singleSubmit', 'form:not([method~="GET"])', onFormSubmit);
-    }
-
+      $(once('form-single-submit', 'body')).on(
+        'submit.singleSubmit',
+        'form:not([method~="GET"])',
+        onFormSubmit,
+      );
+    },
   };
 
+  /**
+   * Sends a 'formUpdated' event each time a form element is modified.
+   *
+   * @param {HTMLElement} element
+   *   The element to trigger a form updated event on.
+   *
+   * @fires event:formUpdated
+   */
   function triggerFormUpdated(element) {
     $(element).trigger('formUpdated');
   }
 
+  /**
+   * Collects the IDs of all form fields in the given form.
+   *
+   * @param {HTMLFormElement} form
+   *   The form element to search.
+   *
+   * @return {Array}
+   *   Array of IDs for form fields.
+   */
   function fieldsList(form) {
-    return [].map.call(form.querySelectorAll('[name][id]'), el => el.id);
+    // We use id to avoid name duplicates on radio fields and filter out
+    // elements with a name but no id.
+    return [].map.call(form.querySelectorAll('[name][id]'), (el) => el.id);
   }
 
+  /**
+   * Triggers the 'formUpdated' event on form elements when they are modified.
+   *
+   * @type {Drupal~behavior}
+   *
+   * @prop {Drupal~behaviorAttach} attach
+   *   Attaches formUpdated behaviors.
+   * @prop {Drupal~behaviorDetach} detach
+   *   Detaches formUpdated behaviors.
+   *
+   * @fires event:formUpdated
+   */
   Drupal.behaviors.formUpdated = {
     attach(context) {
       const $context = $(context);
       const contextIsForm = $context.is('form');
-      const $forms = $(once('form-updated', contextIsForm ? $context : $context.find('form')));
+      const $forms = $(
+        once('form-updated', contextIsForm ? $context : $context.find('form')),
+      );
       let formFields;
 
       if ($forms.length) {
-        $.makeArray($forms).forEach(form => {
+        // Initialize form behaviors, use $.makeArray to be able to use native
+        // forEach array method and have the callback parameters in the right
+        // order.
+        $.makeArray($forms).forEach((form) => {
           const events = 'change.formUpdated input.formUpdated ';
-          const eventHandler = debounce(event => {
+          const eventHandler = debounce((event) => {
             triggerFormUpdated(event.target);
           }, 300);
           formFields = fieldsList(form).join(',');
+
           form.setAttribute('data-drupal-form-fields', formFields);
           $(form).on(events, eventHandler);
         });
       }
-
+      // On ajax requests context is the form element.
       if (contextIsForm) {
         formFields = fieldsList(context).join(',');
+        // @todo replace with form.getAttribute() when #1979468 is in.
         const currentFields = $(context).attr('data-drupal-form-fields');
-
+        // If there has been a change in the fields or their order, trigger
+        // formUpdated.
         if (formFields !== currentFields) {
           triggerFormUpdated(context);
         }
       }
     },
-
     detach(context, settings, trigger) {
       const $context = $(context);
       const contextIsForm = $context.is('form');
-
       if (trigger === 'unload') {
-        once.remove('form-updated', contextIsForm ? $context : $context.find('form')).forEach(form => {
-          form.removeAttribute('data-drupal-form-fields');
-          $(form).off('.formUpdated');
-        });
+        once
+          .remove(
+            'form-updated',
+            contextIsForm ? $context : $context.find('form'),
+          )
+          .forEach((form) => {
+            form.removeAttribute('data-drupal-form-fields');
+            $(form).off('.formUpdated');
+          });
       }
-    }
-
+    },
   };
+
+  /**
+   * Prepopulate form fields with information from the visitor browser.
+   *
+   * @type {Drupal~behavior}
+   *
+   * @prop {Drupal~behaviorAttach} attach
+   *   Attaches the behavior for filling user info from browser.
+   */
   Drupal.behaviors.fillUserInfoFromBrowser = {
     attach(context, settings) {
       const userInfo = ['name', 'mail', 'homepage'];
-      const $forms = $(once('user-info-from-browser', '[data-user-info-from-browser]'));
-
+      const $forms = $(
+        once('user-info-from-browser', '[data-user-info-from-browser]'),
+      );
       if ($forms.length) {
-        userInfo.forEach(info => {
+        userInfo.forEach((info) => {
           const $element = $forms.find(`[name=${info}]`);
           const browserData = localStorage.getItem(`Drupal.visitor.${info}`);
-
           if (!$element.length) {
             return;
           }
-
           const emptyValue = $element[0].value === '';
-          const defaultValue = $element.attr('data-drupal-default-value') === $element[0].value;
-
+          const defaultValue =
+            $element.attr('data-drupal-default-value') === $element[0].value;
           if (browserData && (emptyValue || defaultValue)) {
             $element.each(function (index, item) {
               item.value = browserData;
@@ -120,39 +258,68 @@
           }
         });
       }
-
       $forms.on('submit', () => {
-        userInfo.forEach(info => {
+        userInfo.forEach((info) => {
           const $element = $forms.find(`[name=${info}]`);
-
           if ($element.length) {
             localStorage.setItem(`Drupal.visitor.${info}`, $element[0].value);
           }
         });
       });
-    }
-
+    },
   };
 
-  const handleFragmentLinkClickOrHashChange = e => {
+  /**
+   * Sends a fragment interaction event on a hash change or fragment link click.
+   *
+   * @param {jQuery.Event} e
+   *   The event triggered.
+   *
+   * @fires event:formFragmentLinkClickOrHashChange
+   */
+  const handleFragmentLinkClickOrHashChange = (e) => {
     let url;
-
     if (e.type === 'click') {
-      url = e.currentTarget.location ? e.currentTarget.location : e.currentTarget;
+      url = e.currentTarget.location
+        ? e.currentTarget.location
+        : e.currentTarget;
     } else {
       url = window.location;
     }
-
     const hash = url.hash.substr(1);
-
     if (hash) {
       const $target = $(`#${hash}`);
       $('body').trigger('formFragmentLinkClickOrHashChange', [$target]);
+
+      /**
+       * Clicking a fragment link or a hash change should focus the target
+       * element, but event timing issues in multiple browsers require a timeout.
+       */
       setTimeout(() => $target.trigger('focus'), 300);
     }
   };
 
-  const debouncedHandleFragmentLinkClickOrHashChange = debounce(handleFragmentLinkClickOrHashChange, 300, true);
-  $(window).on('hashchange.form-fragment', debouncedHandleFragmentLinkClickOrHashChange);
-  $(document).on('click.form-fragment', 'a[href*="#"]', debouncedHandleFragmentLinkClickOrHashChange);
-})(jQuery, Drupal, Drupal.debounce);
\ No newline at end of file
+  const debouncedHandleFragmentLinkClickOrHashChange = debounce(
+    handleFragmentLinkClickOrHashChange,
+    300,
+    true,
+  );
+
+  // Binds a listener to handle URL fragment changes.
+  $(window).on(
+    'hashchange.form-fragment',
+    debouncedHandleFragmentLinkClickOrHashChange,
+  );
+
+  /**
+   * Binds a listener to handle clicks on fragment links and absolute URL links
+   * containing a fragment, this is needed next to the hash change listener
+   * because clicking such links doesn't trigger a hash change when the fragment
+   * is already in the URL.
+   */
+  $(document).on(
+    'click.form-fragment',
+    'a[href*="#"]',
+    debouncedHandleFragmentLinkClickOrHashChange,
+  );
+})(jQuery, Drupal, Drupal.debounce);