@jsenv/navi 0.0.1 → 0.1.1

package/src/validation/custom_constraint_validation.js

@@ -0,0 +1,599 @@
+/**
+ * Custom form validation implementation
+ *
+ * This implementation addresses several limitations of the browser's native validation API:
+ *
+ * Limitations of native validation:
+ * - Cannot programmatically detect if validation message is currently displayed
+ * - No ability to dismiss messages with keyboard (e.g., Escape key)
+ * - Requires complex event handling to manage validation message display
+ * - Limited support for storing/managing multiple validation messages
+ * - No customization of validation message appearance
+ *
+ * Design approach:
+ * - Works alongside native validation (which acts as a fallback)
+ * - Proactively detects validation issues before native validation triggers
+ * - Provides complete control over validation message UX
+ * - Supports keyboard navigation and dismissal
+ * - Allows custom styling and positioning of validation messages
+ *
+ * Features:
+ * - Constraint-based validation system with built-in and custom constraints
+ * - Custom validation messages with different severity levels
+ * - Form submission prevention on validation failure
+ * - Validation on Enter key in forms or standalone inputs
+ * - Escape key to dismiss validation messages
+ * - Support for standard HTML validation attributes (required, pattern, type="email")
+ * - Validation messages that follow the input element and adapt to viewport
+ */
+
+import {
+  DISABLED_CONSTRAINT,
+  MAX_CONSTRAINT,
+  MAX_LENGTH_CONSTRAINT,
+  MIN_CONSTRAINT,
+  MIN_LENGTH_CONSTRAINT,
+  PATTERN_CONSTRAINT,
+  REQUIRED_CONSTRAINT,
+  TYPE_EMAIL_CONSTRAINT,
+  TYPE_NUMBER_CONSTRAINT,
+} from "./constraints/native_constraints.js";
+import { READONLY_CONSTRAINT } from "./constraints/readonly_constraint.js";
+import { openValidationMessage } from "./validation_message.js";
+
+let debug = false;
+
+const validationInProgressWeakSet = new WeakSet();
+
+export const requestAction = (
+  target,
+  action,
+  {
+    event,
+    requester = target,
+    actionOrigin,
+    method = "rerun",
+    meta = {},
+    confirmMessage,
+  } = {},
+) => {
+  if (!actionOrigin) {
+    console.warn("requestAction: actionOrigin is required");
+  }
+  let elementToValidate = requester;
+
+  let validationInterface = elementToValidate.__validationInterface__;
+  if (!validationInterface) {
+    validationInterface = installCustomConstraintValidation(elementToValidate);
+  }
+
+  const customEventDetail = {
+    action,
+    actionOrigin,
+    method,
+    event,
+    requester,
+    meta,
+  };
+
+  if (debug) {
+    console.debug(
+      `action requested by`,
+      requester,
+      `(event: "${event?.type}")`,
+    );
+  }
+
+  // Determine what needs to be validated and how to handle the result
+  const isForm = elementToValidate.tagName === "FORM";
+  const formToValidate = isForm ? elementToValidate : elementToValidate.form;
+
+  let isValid = false;
+  let elementForConfirmation = elementToValidate;
+  let elementForDispatch = elementToValidate;
+
+  if (formToValidate) {
+    // Form validation case
+    if (validationInProgressWeakSet.has(formToValidate)) {
+      if (debug) {
+        console.debug(`validation already in progress for`, formToValidate);
+      }
+      return false;
+    }
+    validationInProgressWeakSet.add(formToValidate);
+    setTimeout(() => {
+      validationInProgressWeakSet.delete(formToValidate);
+    });
+
+    // Validate all form elements
+    const formElements = formToValidate.elements;
+    isValid = true; // Assume valid until proven otherwise
+    for (const formElement of formElements) {
+      const elementValidationInterface = formElement.__validationInterface__;
+      if (!elementValidationInterface) {
+        continue;
+      }
+
+      const elementIsValid = elementValidationInterface.checkValidity({
+        fromRequestAction: true,
+        skipReadonly:
+          formElement.tagName === "BUTTON" && formElement !== requester,
+      });
+      if (!elementIsValid) {
+        elementValidationInterface.reportValidity();
+        isValid = false;
+        break;
+      }
+    }
+
+    elementForConfirmation = formToValidate;
+    elementForDispatch = target;
+  } else {
+    // Single element validation case
+    isValid = validationInterface.checkValidity({ fromRequestAction: true });
+    if (!isValid) {
+      if (event) {
+        event.preventDefault();
+      }
+      validationInterface.reportValidity();
+    }
+
+    elementForConfirmation = target;
+    elementForDispatch = target;
+  }
+
+  // If validation failed, dispatch actionprevented and return
+  if (!isValid) {
+    const actionPreventedCustomEvent = new CustomEvent("actionprevented", {
+      detail: customEventDetail,
+    });
+    elementForDispatch.dispatchEvent(actionPreventedCustomEvent);
+    return false;
+  }
+
+  // Validation passed, check for confirmation
+  confirmMessage =
+    confirmMessage ||
+    elementForConfirmation.getAttribute("data-confirm-message");
+  if (confirmMessage) {
+    // eslint-disable-next-line no-alert
+    if (!window.confirm(confirmMessage)) {
+      const actionPreventedCustomEvent = new CustomEvent("actionprevented", {
+        detail: customEventDetail,
+      });
+      elementForDispatch.dispatchEvent(actionPreventedCustomEvent);
+      return false;
+    }
+  }
+
+  // All good, dispatch the action
+  const actionCustomEvent = new CustomEvent("action", {
+    detail: customEventDetail,
+  });
+  if (debug) {
+    console.debug(
+      `element is valid -> dispatch "action" on`,
+      elementForDispatch,
+    );
+  }
+  elementForDispatch.dispatchEvent(actionCustomEvent);
+  return true;
+};
+
+export const closeValidationMessage = (element, reason) => {
+  const validationInterface = element.__validationInterface__;
+  if (!validationInterface) {
+    return false;
+  }
+  const { validationMessage } = validationInterface;
+  if (!validationMessage) {
+    return false;
+  }
+  return validationMessage.close(reason);
+};
+
+export const checkValidity = (element) => {
+  const validationInterface = element.__validationInterface__;
+  if (!validationInterface) {
+    return false;
+  }
+  return validationInterface.checkValidity();
+};
+
+export const installCustomConstraintValidation = (
+  element,
+  elementReceivingValidationMessage = element,
+) => {
+  if (element.tagName === "INPUT" && element.type === "hidden") {
+    elementReceivingValidationMessage = element.form || document.body;
+  }
+
+  const validationInterface = {
+    uninstall: undefined,
+    registerConstraint: undefined,
+    addCustomMessage: undefined,
+    removeCustomMessage: undefined,
+    checkValidity: undefined,
+    reportValidity: undefined,
+    validationMessage: null,
+  };
+
+  const cleanupCallbackSet = new Set();
+  cleanup: {
+    const uninstall = () => {
+      for (const cleanupCallback of cleanupCallbackSet) {
+        cleanupCallback();
+      }
+      cleanupCallbackSet.clear();
+    };
+    validationInterface.uninstall = uninstall;
+  }
+
+  expose_as_node_property: {
+    element.__validationInterface__ = validationInterface;
+    cleanupCallbackSet.add(() => {
+      delete element.__validationInterface__;
+    });
+  }
+
+  const dispatchCancelCustomEvent = (options) => {
+    const cancelEvent = new CustomEvent("cancel", options);
+    element.dispatchEvent(cancelEvent);
+  };
+
+  const closeElementValidationMessage = (reason) => {
+    if (validationInterface.validationMessage) {
+      validationInterface.validationMessage.close(reason);
+      return true;
+    }
+    return false;
+  };
+
+  const constraintSet = new Set();
+  constraintSet.add(DISABLED_CONSTRAINT);
+  constraintSet.add(REQUIRED_CONSTRAINT);
+  constraintSet.add(PATTERN_CONSTRAINT);
+  constraintSet.add(TYPE_EMAIL_CONSTRAINT);
+  constraintSet.add(TYPE_NUMBER_CONSTRAINT);
+  constraintSet.add(MIN_LENGTH_CONSTRAINT);
+  constraintSet.add(MAX_LENGTH_CONSTRAINT);
+  constraintSet.add(MIN_CONSTRAINT);
+  constraintSet.add(MAX_CONSTRAINT);
+  constraintSet.add(READONLY_CONSTRAINT);
+  register_constraint: {
+    validationInterface.registerConstraint = (constraint) => {
+      if (typeof constraint === "function") {
+        constraint = {
+          name: constraint.name || "custom_function",
+          check: constraint,
+        };
+      }
+      constraintSet.add(constraint);
+      return () => {
+        constraintSet.delete(constraint);
+      };
+    };
+  }
+
+  let failedConstraintInfo = null;
+  const validityInfoMap = new Map();
+
+  const resetValidity = ({ fromRequestAction } = {}) => {
+    if (fromRequestAction && failedConstraintInfo) {
+      for (const [key, customMessage] of customMessageMap) {
+        if (customMessage.removeOnRequestAction) {
+          customMessageMap.delete(key);
+        }
+      }
+    }
+
+    for (const [, validityInfo] of validityInfoMap) {
+      if (validityInfo.cleanup) {
+        validityInfo.cleanup();
+      }
+    }
+    validityInfoMap.clear();
+    failedConstraintInfo = null;
+  };
+  cleanupCallbackSet.add(resetValidity);
+
+  const checkValidity = ({ fromRequestAction, skipReadonly } = {}) => {
+    resetValidity({ fromRequestAction });
+    for (const constraint of constraintSet) {
+      const constraintCleanupSet = new Set();
+      const registerChange = (register) => {
+        const registerResult = register(() => {
+          checkValidity();
+        });
+        if (typeof registerResult === "function") {
+          constraintCleanupSet.add(registerResult);
+        }
+      };
+      const cleanup = () => {
+        for (const cleanupCallback of constraintCleanupSet) {
+          cleanupCallback();
+        }
+        constraintCleanupSet.clear();
+      };
+
+      const checkResult = constraint.check(element, {
+        fromRequestAction,
+        skipReadonly,
+        registerChange,
+      });
+      if (!checkResult) {
+        cleanup();
+        continue;
+      }
+      const constraintValidityInfo =
+        typeof checkResult === "string"
+          ? { message: checkResult }
+          : checkResult;
+
+      failedConstraintInfo = {
+        name: constraint.name,
+        constraint,
+        ...constraintValidityInfo,
+        cleanup,
+        reportStatus: "not_reported",
+      };
+      validityInfoMap.set(constraint, failedConstraintInfo);
+    }
+
+    if (!failedConstraintInfo) {
+      closeElementValidationMessage("becomes_valid");
+    }
+
+    return !failedConstraintInfo;
+  };
+  const reportValidity = ({ skipFocus } = {}) => {
+    if (!failedConstraintInfo) {
+      closeElementValidationMessage("becomes_valid");
+      return;
+    }
+    if (failedConstraintInfo.silent) {
+      closeElementValidationMessage("invalid_silent");
+      return;
+    }
+    if (validationInterface.validationMessage) {
+      const { message, level, closeOnClickOutside } = failedConstraintInfo;
+      validationInterface.validationMessage.update(message, {
+        level,
+        closeOnClickOutside,
+      });
+      return;
+    }
+    if (!skipFocus) {
+      element.focus();
+    }
+    const closeOnCleanup = () => {
+      closeElementValidationMessage("cleanup");
+    };
+
+    const elementTarget =
+      failedConstraintInfo.target || elementReceivingValidationMessage;
+
+    validationInterface.validationMessage = openValidationMessage(
+      elementTarget,
+      failedConstraintInfo.message,
+      {
+        level: failedConstraintInfo.level,
+        closeOnClickOutside: failedConstraintInfo.closeOnClickOutside,
+        onClose: () => {
+          cleanupCallbackSet.delete(closeOnCleanup);
+          validationInterface.validationMessage = null;
+          if (failedConstraintInfo) {
+            failedConstraintInfo.reportStatus = "closed";
+          }
+          if (!skipFocus) {
+            element.focus();
+          }
+        },
+      },
+    );
+    failedConstraintInfo.reportStatus = "reported";
+    cleanupCallbackSet.add(closeOnCleanup);
+  };
+  validationInterface.checkValidity = checkValidity;
+  validationInterface.reportValidity = reportValidity;
+
+  const customMessageMap = new Map();
+  custom_message: {
+    constraintSet.add({
+      name: "custom_message",
+      check: () => {
+        for (const [, { message, level }] of customMessageMap) {
+          return { message, level };
+        }
+        return null;
+      },
+    });
+    const addCustomMessage = (
+      key,
+      message,
+      { level = "error", removeOnRequestAction = false } = {},
+    ) => {
+      customMessageMap.set(key, { message, level, removeOnRequestAction });
+      checkValidity();
+      reportValidity();
+      return () => {
+        removeCustomMessage(key);
+      };
+    };
+    const removeCustomMessage = (key) => {
+      if (customMessageMap.has(key)) {
+        customMessageMap.delete(key);
+        checkValidity();
+        reportValidity();
+      }
+    };
+    cleanupCallbackSet.add(() => {
+      customMessageMap.clear();
+    });
+    Object.assign(validationInterface, {
+      addCustomMessage,
+      removeCustomMessage,
+    });
+  }
+
+  close_and_check_on_input: {
+    const oninput = () => {
+      customMessageMap.clear();
+      closeElementValidationMessage("input_event");
+      checkValidity();
+    };
+    element.addEventListener("input", oninput);
+    cleanupCallbackSet.add(() => {
+      element.removeEventListener("input", oninput);
+    });
+  }
+
+  check_on_actionend: {
+    // this ensure we re-check validity (and remove message no longer relevant)
+    // once the action ends (used to remove the NOT_BUSY_CONSTRAINT message)
+    const onactionend = () => {
+      checkValidity();
+    };
+    element.addEventListener("actionend", onactionend);
+    if (element.form) {
+      element.form.addEventListener("actionend", onactionend);
+      cleanupCallbackSet.add(() => {
+        element.form.removeEventListener("actionend", onactionend);
+      });
+    }
+    cleanupCallbackSet.add(() => {
+      element.removeEventListener("actionend", onactionend);
+    });
+  }
+
+  report_on_report_validity_call: {
+    const nativeReportValidity = element.reportValidity;
+    element.reportValidity = () => {
+      reportValidity();
+    };
+    cleanupCallbackSet.add(() => {
+      element.reportValidity = nativeReportValidity;
+    });
+  }
+
+  dispatch_request_submit_call_on_form: {
+    const onRequestSubmit = (form, e) => {
+      if (form !== element.form && form !== element) {
+        return;
+      }
+
+      const requestSubmitCustomEvent = new CustomEvent("requestsubmit", {
+        cancelable: true,
+        detail: { cause: e },
+      });
+      form.dispatchEvent(requestSubmitCustomEvent);
+      if (requestSubmitCustomEvent.defaultPrevented) {
+        e.preventDefault();
+      }
+    };
+    requestSubmitCallbackSet.add(onRequestSubmit);
+    cleanupCallbackSet.add(() => {
+      requestSubmitCallbackSet.delete(onRequestSubmit);
+    });
+  }
+
+  execute_on_form_submit: {
+    const form = element.form || element.tagName === "FORM" ? element : null;
+    if (!form) {
+      break execute_on_form_submit;
+    }
+    const removeListener = addEventListener(form, "submit", (e) => {
+      e.preventDefault();
+      if (debug) {
+        console.debug(`"submit" called -> dispatch "action" on`, form);
+      }
+      const actionCustomEvent = new CustomEvent("action", {
+        detail: {
+          action: null,
+          event: e,
+          method: "rerun",
+          requester: form,
+          meta: {},
+        },
+      });
+      form.dispatchEvent(actionCustomEvent);
+    });
+    cleanupCallbackSet.add(() => {
+      removeListener();
+    });
+  }
+
+  close_on_escape: {
+    const onkeydown = (e) => {
+      if (e.key === "Escape") {
+        if (!closeElementValidationMessage("escape_key")) {
+          dispatchCancelCustomEvent({ detail: { reason: "escape_key" } });
+        }
+      }
+    };
+    element.addEventListener("keydown", onkeydown);
+    cleanupCallbackSet.add(() => {
+      element.removeEventListener("keydown", onkeydown);
+    });
+  }
+
+  cancel_on_blur: {
+    const onblur = () => {
+      if (element.value === "") {
+        dispatchCancelCustomEvent({ detail: { reason: "blur_empty" } });
+        return;
+      }
+      // if we have failed constraint, we cancel too
+      if (failedConstraintInfo) {
+        dispatchCancelCustomEvent({
+          detail: {
+            reason: "blur_invalid",
+            failedConstraintInfo,
+          },
+        });
+        return;
+      }
+    };
+    element.addEventListener("blur", onblur);
+    cleanupCallbackSet.add(() => {
+      element.removeEventListener("blur", onblur);
+    });
+  }
+
+  return validationInterface;
+};
+
+// https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Constraint_validation
+
+const requestSubmitCallbackSet = new Set();
+const requestSubmit = HTMLFormElement.prototype.requestSubmit;
+HTMLFormElement.prototype.requestSubmit = function (submitter) {
+  let prevented = false;
+  const preventDefault = () => {
+    prevented = true;
+  };
+  for (const requestSubmitCallback of requestSubmitCallbackSet) {
+    requestSubmitCallback(this, { submitter, preventDefault });
+  }
+  if (prevented) {
+    return;
+  }
+  requestSubmit.call(this, submitter);
+};
+
+// const submit = HTMLFormElement.prototype.submit;
+// HTMLFormElement.prototype.submit = function (...args) {
+//   const form = this;
+//   if (form.hasAttribute("data-method")) {
+//     console.warn("You must use form.requestSubmit() instead of form.submit()");
+//     return form.requestSubmit();
+//   }
+//   return submit.apply(this, args);
+// };
+
+const addEventListener = (element, event, callback) => {
+  element.addEventListener(event, callback);
+  return () => {
+    element.removeEventListener(event, callback);
+  };
+};

package/src/validation/custom_message.js

@@ -0,0 +1,18 @@
+import { installCustomConstraintValidation } from "./custom_constraint_validation.js";
+
+export const addCustomMessage = (element, key, message, options) => {
+  const customConstraintValidation =
+    element.__validationInterface__ ||
+    (element.__validationInterface__ =
+      installCustomConstraintValidation(element));
+
+  return customConstraintValidation.addCustomMessage(key, message, options);
+};
+
+export const removeCustomMessage = (element, key) => {
+  const customConstraintValidation = element.__validationInterface__;
+  if (!customConstraintValidation) {
+    return;
+  }
+  customConstraintValidation.removeCustomMessage(key);
+};