refactor: Only Allow 1 Event Type to Be Specified for the FormValidityObserver

Although this is a breaking change, it will more easily
allow us to support the `revalidateOn` feature that
we mentioned on GitHub while also maintaining the
parent-child relationship between the `FormObserver` and
the `FormValidityObserver`. (We could technically choose
to break that relationship, but the reusable `observe`
and `unobserve` methods seem to be proving helpful right
now.)

This change also seems more logical because -- practically
speaking -- developers are likely going to choose one
event anyway. They'll have to choose an event that actually
relates to user interaction. And the most common of those
events are `input`, `focusout`, and `change`. However,
the final `input` triggers before `focusout` happens, so
it doesn't make sense to specify both simultaneously.
Similarly, the `change` event will only be relevant for
a subset of the times that the `focusout` event is
triggered, so supplying those two simultaneously also
doesn't make sense. So developers will likely only
supply 1 event at a time.

Author: ITenthusiasm

packages/core/FormValidityObserver.d.ts

@@ -4,7 +4,7 @@
  * - https://github.com/microsoft/TypeScript/issues/55919 (generic constructors)
  * - https://github.com/microsoft/TypeScript/issues/40451 (generic constructors)
  */
-import type { OneOrMany, EventType, ValidatableField } from "./types.d.ts";
+import type { EventType, ValidatableField } from "./types.d.ts";
 
 export type ErrorMessage<M, E extends ValidatableField = ValidatableField> = M | ((field: E) => M);
 
@@ -95,15 +95,10 @@ interface FormValidityObserverConstructor {
    * Provides a way to validate an `HTMLFormElement`'s fields (and to display _accessible_ errors for those fields)
    * in response to the events that the fields emit.
    *
-   * @param types The type(s) of event(s) that trigger(s) form field validation.
+   * @param type The type of event that triggers form field validation.
    */
-  new <
-    T extends OneOrMany<EventType>,
-    M = string,
-    E extends ValidatableField = ValidatableField,
-    R extends boolean = false,
-  >(
-    types: T,
+  new <T extends EventType, M = string, E extends ValidatableField = ValidatableField, R extends boolean = false>(
+    type: T,
     options?: FormValidityObserverOptions<M, E, R>,
   ): FormValidityObserver<M, R>;
 }

packages/core/FormValidityObserver.js

@@ -115,7 +115,7 @@ class FormValidityObserver extends FormObserver {
    * illegal generic constructors?
    */
   /**
-   * @template {import("./types.d.ts").OneOrMany<import("./types.d.ts").EventType>} T
+   * @template {import("./types.d.ts").EventType} T
    * @template [M=string]
    * @template {import("./types.d.ts").ValidatableField} [E=import("./types.d.ts").ValidatableField]
    * @template {boolean} [R=false]
@@ -124,16 +124,16 @@ class FormValidityObserver extends FormObserver {
    * Provides a way to validate an `HTMLFormElement`'s fields (and to display _accessible_ errors for those fields)
    * in response to the events that the fields emit.
    *
-   * @param {T} types The type(s) of event(s) that trigger(s) form field validation.
+   * @param {T} type The type of event that triggers form field validation.
    * @param {FormValidityObserverOptions<M, E, R>} [options]
    * @returns {FormValidityObserver<M, R>}
    */
 
   /**
-   * @param {import("./types.d.ts").OneOrMany<import("./types.d.ts").EventType>} types
+   * @param {import("./types.d.ts").EventType} type
    * @param {FormValidityObserverOptions<M, import("./types.d.ts").ValidatableField, R>} [options]
    */
-  constructor(types, options) {
+  constructor(type, options) {
     /**
      * Event listener used to validate form fields in response to user interactions
      *
@@ -145,7 +145,7 @@ class FormValidityObserver extends FormObserver {
       if (fieldName) this.validateField(fieldName);
     };
 
-    super(types, eventListener, { passive: true, capture: options?.useEventCapturing });
+    super(type, eventListener, { passive: true, capture: options?.useEventCapturing });
     this.#scrollTo = options?.scroller ?? defaultScroller;
     this.#renderError = /** @type {any} Necessary because of double `M`s */ (options?.renderer ?? defaultErrorRenderer);
     this.#renderByDefault = /** @type {any} Necessary because of double `R`s */ (options?.renderByDefault);

packages/core/__tests__/FormValidityObserver.test.ts

@@ -4,14 +4,14 @@ import createFormValidityObserver from "../createFormValidityObserver.js";
 import type { EventType } from "../index.d.ts";
 
 describe("Create Form Validity Observer (Function)", () => {
-  const types = Object.freeze(["input", "focusout"] as const) satisfies ReadonlyArray<EventType>;
+  const type = "input" satisfies EventType;
 
   // TODO: Can we get rid of the weird `void` thing?
   // Keep things clean between each test by automatically restoring anything we may have spied on
   beforeEach(vi.restoreAllMocks as () => void);
 
   it("Generates a `FormValidityObserver` (enhanced)", () => {
-    expect(createFormValidityObserver(types)).toEqual(expect.any(FormValidityObserver));
+    expect(createFormValidityObserver(type)).toEqual(expect.any(FormValidityObserver));
   });
 
   it("Exposes `bound` versions of the `FormValidityObserver`'s methods", () => {
@@ -29,7 +29,7 @@ describe("Create Form Validity Observer (Function)", () => {
     boundMethods.forEach((method) => vi.spyOn(FormValidityObserver.prototype[method], "bind"));
 
     /* ---------- Run Assertions ---------- */
-    const observer = createFormValidityObserver(types);
+    const observer = createFormValidityObserver(type);
 
     boundMethods.forEach((method) => {
       expect(FormValidityObserver.prototype[method].bind).toHaveBeenCalledTimes(1);

packages/lit/__tests__/createFormValidityObserver.test.ts

@@ -3,16 +3,16 @@ import FormValidityObserver from "@form-observer/core/FormValidityObserver";
 /**
  * Creates a version of the {@link FormValidityObserver} that's more convenient for `Lit` apps
  *
- * @template {import("./index.d.ts").OneOrMany<import("./index.d.ts").EventType>} T
+ * @template {import("./index.d.ts").EventType} T
  * @template [M=string]
  * @template {import("./index.d.ts").ValidatableField} [E=import("./index.d.ts").ValidatableField]
  * @template {boolean} [R=false]
- * @param {T} types
+ * @param {T} type
  * @param {import("./index.d.ts").FormValidityObserverOptions<M, E, R>} [options]
  * @returns {FormValidityObserver<M, R>}
  */
-export default function createFormValidityObserver(types, options) {
-  const observer = new FormValidityObserver(types, options);
+export default function createFormValidityObserver(type, options) {
+  const observer = new FormValidityObserver(type, options);
 
   /* -------------------- Bindings -------------------- */
   // Form Observer Methods

packages/lit/createFormValidityObserver.js

@@ -9,13 +9,13 @@ import type { PreactValidationErrors } from "../types.d.ts";
 import type { EventType, FormField, ValidatableField } from "../index.d.ts";
 
 describe("Create Form Validity Observer (Function)", () => {
-  const types = Object.freeze(["input", "focusout"] as const) satisfies ReadonlyArray<EventType>;
+  const type = "input" satisfies EventType;
 
   // Keep things clean between each test by automatically restoring anything we may have spied on
   beforeEach(vi.restoreAllMocks as () => void);
 
   it("Generates a `FormValidityObserver` (enhanced)", () => {
-    expect(createFormValidityObserver(types)).toEqual(expect.any(FormValidityObserver));
+    expect(createFormValidityObserver(type)).toEqual(expect.any(FormValidityObserver));
   });
 
   it("Exposes `bound` versions of the `FormValidityObserver`'s methods (excluding `configure`)", () => {
@@ -33,7 +33,7 @@ describe("Create Form Validity Observer (Function)", () => {
     boundMethods.forEach((method) => vi.spyOn(FormValidityObserver.prototype[method], "bind"));
 
     /* ---------- Run Assertions ---------- */
-    const observer = createFormValidityObserver(types);
+    const observer = createFormValidityObserver(type);
 
     boundMethods.forEach((method) => {
       expect(FormValidityObserver.prototype[method].bind).toHaveBeenCalledTimes(1);
@@ -48,7 +48,7 @@ describe("Create Form Validity Observer (Function)", () => {
     vi.spyOn(FormValidityObserver.prototype[configure], "bind");
 
     // Run Assertions
-    const observer = createFormValidityObserver(types);
+    const observer = createFormValidityObserver(type);
     expect(FormValidityObserver.prototype[configure].bind).toHaveBeenCalledTimes(1);
     expect(FormValidityObserver.prototype[configure].bind).toHaveBeenCalledWith(observer);
     expect(FormValidityObserver.prototype[configure].bind).not.toHaveReturnedWith(observer[configure]);
@@ -58,7 +58,7 @@ describe("Create Form Validity Observer (Function)", () => {
   // eslint-disable-next-line vitest/no-disabled-tests
   it.skip("Uses a default `renderer` that accepts `Renderable Preact Values`", () => {
     /* ---------- Setup ---------- */
-    const { autoObserve, setFieldError, clearFieldError } = createFormValidityObserver(types[0]);
+    const { autoObserve, setFieldError, clearFieldError } = createFormValidityObserver(type);
 
     const { unmount } = render(
       <form ref={autoObserve()}>
@@ -132,7 +132,7 @@ describe("Create Form Validity Observer (Function)", () => {
         const message = "Only numbers are allowed!";
         vi.spyOn(FormValidityObserver.prototype, "observe");
         vi.spyOn(FormValidityObserver.prototype, "unobserve");
-        const { autoObserve, configure } = createFormValidityObserver(types[0]);
+        const { autoObserve, configure } = createFormValidityObserver(type);
 
         /* ---------- Assertions ---------- */
         const { unmount } = render(
@@ -170,9 +170,9 @@ describe("Create Form Validity Observer (Function)", () => {
         const labels = { default: "Default Config", true: "Explicit True Option", false: "Explicit False Option" };
         const novalidate = "novalidate";
 
-        const { autoObserve: autoObserveDefault } = createFormValidityObserver(types[0]);
-        const { autoObserve: autoObserveTrue } = createFormValidityObserver(types[0]);
-        const { autoObserve: autoObserveFalse } = createFormValidityObserver(types[0]);
+        const { autoObserve: autoObserveDefault } = createFormValidityObserver(type);
+        const { autoObserve: autoObserveTrue } = createFormValidityObserver(type);
+        const { autoObserve: autoObserveFalse } = createFormValidityObserver(type);
 
         // Assertions
         render(
@@ -196,7 +196,7 @@ describe("Create Form Validity Observer (Function)", () => {
 
       it("ONLY configures the error messages for the custom validation properties", () => {
         vi.spyOn(FormValidityObserver.prototype, "configure");
-        const observer = createFormValidityObserver(types[0]);
+        const observer = createFormValidityObserver(type);
 
         const errorMessages: Pick<ConstraintValues, "badinput" | "validate"> = {
           badinput: (field) => `This ${field.tagName} element isn't looking good` as const,
@@ -209,7 +209,7 @@ describe("Create Form Validity Observer (Function)", () => {
 
       it("ONLY configures the props for the HTML attributes when the value-only variant is used", () => {
         vi.spyOn(FormValidityObserver.prototype, "configure");
-        const observer = createFormValidityObserver(types[0]);
+        const observer = createFormValidityObserver(type);
 
         const errorMessages: Omit<ConstraintValues, "badinput" | "validate"> = {
           required: true,
@@ -228,7 +228,7 @@ describe("Create Form Validity Observer (Function)", () => {
 
       it("Configures the prop AND the error for the `required` constraint when its value is an error message", () => {
         vi.spyOn(FormValidityObserver.prototype, "configure");
-        const observer = createFormValidityObserver(types[0]);
+        const observer = createFormValidityObserver(type);
 
         // Regular Error Message
         const configWithErrorMessage = { required: "This field is bad" };
@@ -243,7 +243,7 @@ describe("Create Form Validity Observer (Function)", () => {
 
       it("Configures the props AND the error messages for the HTML attributes when the object variant is used", () => {
         vi.spyOn(FormValidityObserver.prototype, "configure");
-        const observer = createFormValidityObserver(types[0]);
+        const observer = createFormValidityObserver(type);
 
         const errorMessages: Omit<ConstraintValues, "badinput" | "validate"> = {
           required: { value: true, message: (field) => `<p>${field.tagName} required</p>`, render: true },
@@ -264,7 +264,7 @@ describe("Create Form Validity Observer (Function)", () => {
 
       it("DOES NOT configure any props OR error messages when `undefined` is used", () => {
         vi.spyOn(FormValidityObserver.prototype, "configure");
-        const observer = createFormValidityObserver(types[0]);
+        const observer = createFormValidityObserver(type);
 
         // Undefined Configurations
         const undefinedErrorMessages: PreactValidationErrors<string> = {
@@ -286,7 +286,7 @@ describe("Create Form Validity Observer (Function)", () => {
 
       it("DOES NOT configure the prop OR the error for the `required` constraint when its value is `false`", () => {
         vi.spyOn(FormValidityObserver.prototype, "configure");
-        const observer = createFormValidityObserver(types[0]);
+        const observer = createFormValidityObserver(type);
 
         // `required = false` via Value-Only Variant
         expect(observer.configure(name, { required: false })).toStrictEqual({ name });
@@ -299,7 +299,7 @@ describe("Create Form Validity Observer (Function)", () => {
 
       it("Always returns the `name` prop for the field", () => {
         vi.spyOn(FormValidityObserver.prototype, "configure");
-        const observer = createFormValidityObserver(types[0]);
+        const observer = createFormValidityObserver(type);
 
         expect(observer.configure(name, {})).toStrictEqual({ name });
         expect(FormValidityObserver.prototype.configure).toHaveBeenCalledWith(name, {});
@@ -312,7 +312,7 @@ describe("Create Form Validity Observer (Function)", () => {
           const renderer = (_errorContainer: HTMLElement, _errorMessage: StringOrElement | null) => undefined;
 
           vi.spyOn(FormValidityObserver.prototype, "configure");
-          const observer = createFormValidityObserver(types[0], { renderer, renderByDefault: true });
+          const observer = createFormValidityObserver(type, { renderer, renderByDefault: true });
 
           // Test a Renderable Error Message
           const renderable = { type: "DOMString", value: "No" } as const;

packages/preact/__tests__/createFormValidityObserver.test.tsx

@@ -3,17 +3,17 @@ import FormValidityObserver from "@form-observer/core/FormValidityObserver";
 /**
  * Creates an enhanced version of the {@link FormValidityObserver} that's more convenient for `Preact` apps
  *
- * @template {import("./index.d.ts").OneOrMany<import("./index.d.ts").EventType>} T
+ * @template {import("./index.d.ts").EventType} T
  * @template [M=string]
  * @template {import("./index.d.ts").ValidatableField} [E=import("./index.d.ts").ValidatableField]
  * @template {boolean} [R=false]
- * @param {T} types
+ * @param {T} type
  * @param {import("./index.d.ts").FormValidityObserverOptions<M, E, R>} [options]
  * @returns {import("./types.d.ts").PreactFormValidityObserver<M, R>}
  */
-export default function createFormValidityObserver(types, options) {
+export default function createFormValidityObserver(type, options) {
   const observer = /** @type {import("./types.d.ts").PreactFormValidityObserver<M, R>} */ (
-    /** @type {unknown} */ (new FormValidityObserver(types, options))
+    /** @type {unknown} */ (new FormValidityObserver(type, options))
   );
 
   /* -------------------- Bindings -------------------- */