Initial Drupal 11 with DDEV setup

web/core/misc/form.js

@@ -0,0 +1,334 @@
+/**
+ * @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');
+
+    if (!this[0] || !callback) {
+      return '';
+    }
+
+    const result = callback(this[0]);
+
+    return result ? result.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)
+        // 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 seconds, or even milliseconds. 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 = new URLSearchParams(
+          new FormData(e.target),
+        ).toString();
+        const previousValues = $form.attr('data-drupal-form-submit-last');
+        if (previousValues === formValues) {
+          e.preventDefault();
+        } else {
+          $form.attr('data-drupal-form-submit-last', formValues);
+        }
+      }
+
+      $(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) {
+    // 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.tagName === 'FORM';
+      const $forms = $(
+        once('form-updated', contextIsForm ? $context : $context.find('form')),
+      );
+      let formFields;
+
+      if ($forms.length) {
+        // 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) => {
+            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.tagName === 'FORM';
+      if (trigger === 'unload') {
+        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]'),
+      );
+      if ($forms.length) {
+        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;
+          if (browserData && (emptyValue || defaultValue)) {
+            $element.each(function (index, item) {
+              item.value = browserData;
+            });
+          }
+        });
+      }
+      $forms.on('submit', () => {
+        userInfo.forEach((info) => {
+          const $element = $forms.find(`[name=${info}]`);
+          if ($element.length) {
+            localStorage.setItem(`Drupal.visitor.${info}`, $element[0].value);
+          }
+        });
+      });
+    },
+  };
+
+  /**
+   * 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;
+    } else {
+      url = window.location;
+    }
+    const hash = url.hash.substring(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,
+  );
+
+  // 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);