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

docs/extras/design-decisions.md

@@ -12,6 +12,24 @@ This file is similar to a `Changelog`: It specifies the dates (in descending ord
 
 It's possible that the need for this is already captured in the concept of `PR` (Pull Request) history. We will try to run with this approach _and_ the approach of PRs before coming to a final decision on what to use to accomplish this history-preserving goal.
 
+## 2024-04-28
+
+### Only Allow One (1) Event Type to Be Passed to the `FormValidityObserver` Constructor
+
+Although this is a breaking change, it is one that 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.)
+
+It technically isn't _that_ difficult to continue supporting an array of strings for the `types` argument of the `FormValidityObserver` constructor. But the (very small) additional effort for this support did not seem worth it.
+
+Practically speaking, most (if not all) developers are likely going to choose only one event type anyway. And they'll have to choose one of the events that actually relate to user interaction (so that the form is only validated as users interact with it). The most common of these events are `input`, `focusout` (the bubbling version of the `blur` event), and `change`. But each of these events renders the other ones irrelevant.
+
+For example, the last `input` event that's triggered for a form field will always be triggered _before_ `change` or `focusout`. Consequently, it doesn't make sense to add `change` _or_ `focusout` to the `types` argument of the `FormValidityObserver` constructor when `input` is supplied. The developer would only need to specify the `input` event itself.
+
+Similarly, the `change` event is only fired a _subset_ of the times that the `focusout` event is fired. (There are technically exceptions to this rule, such as `<select>` and `<input type="checkbox">`. But practically speaking, this rule holds for all form controls -- including those.) So instead of specifying both events, a developer would only need to specify the `focusout` event. Finally, if a developer wants to respond to `change` events exclusively, then they will only specify _that_ event. Neither `focusout` nor `input` could be added in that scenario because it would cause the form controls to be validated too frequently.
+
+In the end, whichever event type is chosen, it is only practical for the developer to specify 1 event. Technically speaking, developers could try to specify custom events. But those events would likely be emitted in _response_ to `input`/`focusout`/`change` events anyway. So everything ultimately comes down to those 3 events.
+
+In conclusion, it will be simpler for us to only allow 1 event to be specified for the `types` argument moving forward. Since this is also what will happen naturally (and since enforcing this might protect some developers from unexpected footguns), this seems like a good change.
+
 ## 2023-08-20
 
 ### Deprecate the `FormValidityObserver.validateFields(names: string[])` Overload

docs/form-validity-observer/README.md

@@ -87,9 +87,9 @@ As expected for any form validation library, we also support the following featu
 The `FormValidityObserver()` constructor creates a new observer and configures it with the `options` that you pass in. Because the `FormValidityObserver` only focuses on one task, it has a simple constructor with no overloads.
 
 <dl>
-  <dt id="form-validity-observer-parameters-types"><code>types</code></dt>
+  <dt id="form-validity-observer-parameters-types"><code>type: EventType</code></dt>
   <dd>
-    A string <em>or</em> an array of strings representing the type(s) of event(s) that should cause a form's field to be validated. As with the <code>FormObserver</code>, the string(s) can be <a href="https://developer.mozilla.org/en-US/docs/Web/Events">commonly recognized</a> event types <em>or</em> your own <a href="../form-observer/guides.md#supporting-custom-event-types">custom</a> event types.
+    A string representing the type of event that should cause a form's field to be validated. As with the <code>FormObserver</code>, the string can be a <a href="https://developer.mozilla.org/en-US/docs/Web/Events">commonly recognized</a> event type <em>or</em> your own <a href="../form-observer/guides.md#supporting-custom-event-types">custom</a> event type. But in the case of the <code>FormValidityObserver</code>, only one event type may be specified.
   </dd>
 
   <dt id="form-validity-observer-parameters-options"><code>options</code> (Optional)</dt>

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);