feat: Support Default Error Messages for Observed Forms

This enables developer to remove redundant/repetitive
code from their applications. It also empower developers
to have a central, more ergonomic way to use validation
tools like Zod.

Author: ITenthusiasm

TODO.md

@@ -6,6 +6,7 @@
 
 ## Documentation
 
+- [ ] Add more detailed examples of how to use `Zod` with the `defaultErrors.validate` option.
 - [ ] Figure out a Logo for the `enthusiastic-js` Organization and maybe the Form Observer package?
 - [ ] In the interest of time, we're probably going to have to do the bare minimum when it comes to the documentation. Make the API clear, give some helpful examples, etc. After we've release the first draft of the project, we can start thinking about how to "perfect" the docs. But for now, don't get too paranoid about the wording.
 - [ ] Adding demos somewhere in this repo (or in something like a CodeSandbox) would likely be helpful for developers. **Edit**: We now have examples for the `FormValidityObserver`. Would examples for the `FormObserver` or the `FormStorageObserver` also be helpful?

docs/form-validity-observer/README.md

@@ -116,6 +116,17 @@ The `FormValidityObserver()` constructor creates a new observer and configures i
           The <code>renderer</code> defaults to a function that accepts error messages of type <code>string</code> and renders them to the DOM as raw HTML.
         </p>
       </dd>
+      <dt id="form-validity-observer-options-default-errors"><code>defaultErrors: ValidationErrors&lt;M, E&gt;</code></dt>
+      <dd>
+        <p>
+          Configures the default error messages to display for the validation constraints. (See the <a href="#method-formvalidityobserverconfigureename-string-errormessages-validationerrorsm-e-void"><code>configure</code></a> method for more details about error message configuration, and refer to the <a href="./types.md#validationerrorsm-e"><code>ValidationErrors</code></a> type for more details about validation constraints.)
+        </p>
+        <p>
+          <blockquote>
+            <strong>Note: The <code>defaultErrors.validate</code> option will provide a default custom validation function for <em>all</em> fields in your form.</strong> This is primarily useful if you have a reusable validation function that you want to apply to all of your form's fields (for example, if you are using <a href="https://zod.dev">Zod</a>). See <a href="./guides.md#getting-the-most-out-of-the-defaulterrors-option"><i>Getting the Most out of the <code>defaultErrors</code></i> Option</a> for examples on how to use this option effectively.
+          </blockquote>
+        </p>
+      </dd>
     </dl>
   </dd>
 </dl>
@@ -204,11 +215,11 @@ form1.elements[0].dispatchEvent(new FocusEvent("focusout")); // Does nothing
 
 ### Method: `FormValidityObserver.configure<E>(name: string, errorMessages: `[`ValidationErrors<M, E>`](./types.md#validationerrorsm-e)`): void`
 
-Configures the error messages that will be displayed for a form field's validation constraints. If an error message is not configured for a validation constraint, then the field's [`validationMessage`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validationMessage) will be used instead. For [native form fields](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements), the browser automatically supplies a default `validationMessage` depending on the broken constraint.
+Configures the error messages that will be displayed for a form field's validation constraints. If an error message is not configured for a validation constraint and there is no corresponding [default configuration](#form-validity-observer-options-default-errors), then the field's [`validationMessage`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validationMessage) will be used instead. For [native form fields](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements), the browser automatically supplies a default `validationMessage` depending on the broken constraint.
 
-> Note: If the field is _only_ using the browser's default error messages, it does _not_ need to be `configure`d.
+> Note: If the field is _only_ using the configured [`defaultErrors`](#form-validity-observer-options-default-errors) and/or the browser's default error messages, it _does not_ need to be `configure`d.
 
-The Form Element Type, `E`, represents the form field being configured. This type is inferred from the `errorMessages` configuration and defaults to a general [`ValidatableField`](./types.md#validatablefield).
+The Field Element Type, `E`, represents the form field being configured. This type is inferred from the `errorMessages` configuration and defaults to a general [`ValidatableField`](./types.md#validatablefield).
 
 #### Parameters
 
@@ -297,7 +308,7 @@ When the `focus` option is `false`, you can consider `validateField()` to be an
 
 Marks the form field having the specified `name` as invalid (via the [`[aria-invalid="true"]`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) attribute) and applies the provided error `message` to it. Typically, you shouldn't need to call this method manually; but in rare situations it might be helpful.
 
-The Form Element Type, `E`, represents the invalid form field. This type is inferred from the error `message` if it is a function. Otherwise, `E` defaults to a general [`ValidatableField`](./types.md#validatablefield).
+The Field Element Type, `E`, represents the invalid form field. This type is inferred from the error `message` if it is a function. Otherwise, `E` defaults to a general [`ValidatableField`](./types.md#validatablefield).
 
 #### Parameters
 

docs/form-validity-observer/guides.md

@@ -4,6 +4,7 @@ Here you'll find helpful tips on how to use the `FormValidityObserver` effective
 
 - [Enabling/Disabling Accessible Error Messages](#enabling-accessible-error-messages-during-form-submissions)
 - [Keeping Track of Visited/Dirty Fields](#keeping-track-of-visiteddirty-fields)
+- [Getting the Most out of the `defaultErrors` option](#getting-the-most-out-of-the-defaulterrors-option)
 - [Keeping Track of Form Data](#keeping-track-of-form-data)
 - [Recommendations for Conditionally Rendered Fields](#recommendations-for-conditionally-rendered-fields)
 - [Recommendations for Styling Form Fields and Their Error Messages](#recommendations-for-styling-form-fields-and-their-error-messages)
@@ -129,6 +130,150 @@ To get an idea of how these event listeners would function, you can play around
 
 You can learn more about what can be done with forms using pure JS on our [Philosophy](../extras/philosophy.md#avoid-unnecessary-overhead-and-reinventing-the-wheel) page.
 
+## Getting the Most out of the `defaultErrors` Option
+
+Typically, we want the error messages in our application to be consistent. Unfortunately, this can sometimes cause us to write the same error messages over and over again. For example, consider a message that might be displayed for the `required` constraint:
+
+```html
+<form>
+  <label for="first-name">First Name</label>
+  <input id="first-name" type="text" required aria-describedby="first-name-error" />
+  <div id="first-name-error" role="alert"></div>
+
+  <label for="last-name">Last Name</label>
+  <input id="last-name" type="text" required aria-describedby="last-name-error" />
+  <div id="last-name-error" role="alert"></div>
+
+  <label for="email">Email</label>
+  <input id="email" type="email" required aria-describedby="email-error" />
+  <div id="email-error" role="alert"></div>
+
+  <!-- Other Fields ... -->
+</div>
+```
+
+We might configure our error messages like so
+
+```js
+const observer = new FormValidityObserver("focusout");
+observer.configure("first-name", { required: "First Name is required." });
+observer.configure("last-name", { required: "Last Name is required." });
+observer.configure("email", { required: "Email is required." });
+// Configurations for other fields ...
+```
+
+But this is redundant (and consequently, error-prone). Since all of our error messages for the `required` constraint follow the same format (`"<FIELD_NAME> is required"`), it would be better for us to use the [`defaultErrors`](./README.md#form-validity-observer-options-default-errors) configuration option instead.
+
+```js
+const observer = new FormValidityObserver("focusout", {
+  defaultErrors: {
+    required: (field) => `${field.labels?.[0].textContent ?? "This field"} is required.`;
+  },
+});
+```
+
+This gives us one consistent way to define the `required` error message for _all_ of our fields. Of course, it's possible that not all of your form controls will be labeled by a `<label>` element. For instance, a `radiogroup` is typically labeled by a `<legend>` instead. In this case, you may choose to make the error message more generic
+
+```js
+const observer = new FormValidityObserver("focusout", {
+  defaultErrors: { required: "This field is required" },
+});
+```
+
+Or you may choose to make the error message more flexible
+
+```js
+const observer = new FormValidityObserver("focusout", {
+  defaultErrors: {
+    required(field) {
+      if (field instanceof HTMLInputElement && field.type === "radio") {
+        const radiogroup = input.closest("fieldset[role='radiogroup']");
+        const legend = radiogroup.firstElementChild.matches("legend") ? radiogroup.firstElementChild : null;
+        return `${legend?.textContent ?? "This field"} is required.`;
+      }
+
+      return `${field.labels?.[0].textContent ?? "This field"} is required.`;
+    },
+  },
+});
+```
+
+And if you ever need a _unique_ error message for a specific field, you can still configure it explicitly.
+
+```js
+const observer = new FormValidityObserver("focusout", {
+  defaultErrors: { required: "This field is required" },
+});
+
+observer.configure("my-unique-field", { required: "This field has a unique `required` error!" });
+```
+
+### Default Validation Functions
+
+The `validate` option in the `defaultErrors` object provides a default custom validation function for _all_ of the fields in your form. This can be helpful if you have a reusable validation function that you want to apply to all of your form's fields. For example, if you're using [`Zod`](https://zod.dev) to validate your form data, you could do something like this:
+
+```js
+const schema = z.object({
+  "first-name": z.string(),
+  "last-name": z.string(),
+  email: z.string().email(),
+});
+
+const observer = new FormValidityObserver("focusout", {
+  defaultErrors: {
+    validate(field) {
+      const result = schema.shape[field.name].safeParse(field.value);
+      // Extract field's error message from `result`
+      return errorMessage;
+    },
+  },
+});
+```
+
+By leveraging `defaultErrors.validate`, you can easily use Zod (or any other validation tool) on your frontend. If you're using an SSR framework, you can use the exact same tool on your backend. It's the best of both worlds!
+
+### Zod Validation with Nested Fields
+
+For more complex form structures (e.g., "Nested Fields" as objects or arrays), you will need to write some advanced logic to make sure that you access the correct `safeParse` function. For example, if you have a field named `address.name.first`, then you'll need to recursively follow the path from `address` to `first` to access the correct `safeParse` function. The [`shape`](https://zod.dev/?id=shape) property (for objects) and the [`element`](https://zod.dev/?id=element) property (for arrays) in Zod will help you accomplish this. Alternatively, you can flatten your object structure entirely:
+
+```js
+const schema = z.object({
+  "address.name.first": z.string(),
+  "address.name.last": z.string(),
+  "address.city": z.string(),
+  // Other fields...
+});
+```
+
+This enables you to use the approach that we showed above without having to write any recursive logic. It's arguably more performant than defining and walking through nested objects, but it requires you to be doubly sure that you're spelling all of your fields' names correctly. Also note that the logic for handling arrays in this example would still take a little effort and may require some recursion. However, this logic shouldn't be too difficult to write.
+
+If there's sufficient interest from the community, then we may add some Zod helper functions to our packages to take this burden off of developers.
+
+### Zod Validation Using Existing Libraries
+
+Another option is to use an existing library that validates forms with Zod (e.g., `@conform-to/zod`) and to extract the error messages from that tool. For example, you might do something like the following:
+
+```js
+import { FormValidityObserver } from "@form-observer";
+import { parseWithZod } from "@conform-to/zod";
+import { z } from "zod";
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string(),
+});
+
+const observer = new FormValidityObserver("focusout", {
+  defaultErrors: {
+    validate(field) {
+      const results = parseWithZod(new FormData(field.form), schema);
+      // Grab the correct error message from `results` object by using `field.name`.
+      return errorMessage;
+    },
+  },
+});
+```
+
 ## Keeping Track of Form Data
 
 Many form libraries offer stateful solutions for managing the data in your forms as JSON. But there are a few disadvantages to this approach:

docs/form-validity-observer/integrations/README.md

@@ -128,13 +128,14 @@ We'll walk you through the process by going step-by-step on how we made our `Sve
 The first step is easy. Just create a function that instantiates and returns a `FormValidityObserver`. Because this function will only be creating an augmented `FormValidityObserver`, it should accept the same arguments as the class's [constructor](../README.md#constructor-formvalidityobservertypes-options). The return type will be an `interface` that represents the enhanced observer, but we won't add anything to it yet.
 
 ```ts
-import type { EventType, OneOrMany, FormValidityObserverOptions } from "@form-observer/core";
+import type { EventType, OneOrMany, ValidatableField, FormValidityObserverOptions } from "@form-observer/core";
 import FormValidityObserver from "@form-observer/core/FormValidityObserver";
 
-function createFormValidityObserver<T extends OneOrMany<EventType>, M = string>(
-  types: T,
-  options?: FormValidityObserverOptions<M>,
-): SvelteFormValidityObserver<M> {
+function createFormValidityObserver<
+  T extends OneOrMany<EventType>,
+  M = string,
+  E extends ValidatableField = ValidatableField,
+>(types: T, options?: FormValidityObserverOptions<M, E>): SvelteFormValidityObserver<M> {
   const observer = new FormValidityObserver(types, options) as unknown as SvelteFormValidityObserver<M>;
   return observer;
 }
@@ -157,10 +158,11 @@ In order to ensure that all of the `FormValidityObserver`'s methods function pro
 ```ts
 // Imports ...
 
-function createFormValidityObserver<T extends OneOrMany<EventType>, M = string>(
-  types: T,
-  options?: FormValidityObserverOptions<M>,
-): SvelteFormValidityObserver<M> {
+function createFormValidityObserver<
+  T extends OneOrMany<EventType>,
+  M = string,
+  E extends ValidatableField = ValidatableField,
+>(types: T, options?: FormValidityObserverOptions<M, E>): SvelteFormValidityObserver<M> {
   const observer = new FormValidityObserver(types, options) as unknown as SvelteFormValidityObserver<M>;
 
   /* ---------- Bindings ---------- */
@@ -193,14 +195,15 @@ In this step, we create a reusable utility function that will enable us to autom
 Most JS frameworks create a way for you to accomplish this easily with utility functions. In [`React`](https://react.dev/reference/react-dom/components/common#ref-callback) or [`Vue`](https://vuejs.org/api/built-in-special-attributes.html#ref), you would pass a `ref` callback to an `HTMLFormElement`. In `Svelte`, the idiomatic way to accomplish this is with [`actions`](https://learn.svelte.dev/tutorial/actions):
 
 ```ts
-import type { EventType, OneOrMany, FormValidityObserverOptions } from "@form-observer/core";
+import type { EventType, OneOrMany, ValidatableField, FormValidityObserverOptions } from "@form-observer/core";
 import FormValidityObserver from "@form-observer/core/FormValidityObserver";
 import type { ActionReturn } from "svelte/action";
 
-function createFormValidityObserver<T extends OneOrMany<EventType>, M = string>(
-  types: T,
-  options?: FormValidityObserverOptions<M>,
-): SvelteFormValidityObserver<M> {
+function createFormValidityObserver<
+  T extends OneOrMany<EventType>,
+  M = string,
+  E extends ValidatableField = ValidatableField,
+>(types: T, options?: FormValidityObserverOptions<M, E>): SvelteFormValidityObserver<M> {
   const observer = new FormValidityObserver(types, options) as unknown as SvelteFormValidityObserver<M>;
 
   /* ---------- Bindings ---------- */
@@ -402,10 +405,11 @@ The hardest part of this process is defining the TypeScript types. With that out
 ```ts
 // Imports ...
 
-export default function createFormValidityObserver<T extends OneOrMany<EventType>, M = string>(
-  types: T,
-  options?: FormValidityObserverOptions<M>,
-): SvelteFormValidityObserver<M> {
+export default function createFormValidityObserver<
+  T extends OneOrMany<EventType>,
+  M = string,
+  E extends ValidatableField = ValidatableField,
+>(types: T, options?: FormValidityObserverOptions<M, E>): SvelteFormValidityObserver<M> {
   const observer = new FormValidityObserver(types, options) as unknown as SvelteFormValidityObserver<M>;
 
   /* ---------- Bindings ---------- */

docs/form-validity-observer/integrations/preact.md

@@ -81,7 +81,7 @@ Remember that `autoObserve` is simply a convenience utility for calling `observe
 
 An enhanced version of [`FormValidityObserver.configure`](../README.md#method-formvalidityobserverconfigureename-string-errormessages-validationerrorsm-e-void) for `Preact`. In addition to configuring a field's error messages, it generates the props that should be applied to the field based on the provided arguments.
 
-> Note: If the field is _only_ using the browser's default error messages, it does _not_ need to be `configure`d.
+> Note: If the field is _only_ using the configured [`defaultErrors`](../README.md#form-validity-observer-options-default-errors) and/or the browser's default error messages, it _does not_ need to be `configure`d.
 
 The `PreactValidationErrors<M, E>` type is an enhanced version of the core [`ValidationErrors<M, E>`](../types.md#validationerrorsm-e) type. Here is how `PreactValidationErrors` compares to `ValidationErrors`.
 

docs/form-validity-observer/integrations/react.md

@@ -91,7 +91,7 @@ Remember that `autoObserve` is simply a convenience utility for calling `observe
 
 An enhanced version of [`FormValidityObserver.configure`](../README.md#method-formvalidityobserverconfigureename-string-errormessages-validationerrorsm-e-void) for `React`. In addition to configuring a field's error messages, it generates the props that should be applied to the field based on the provided arguments.
 
-> Note: If the field is _only_ using the browser's default error messages, it does _not_ need to be `configure`d.
+> Note: If the field is _only_ using the configured [`defaultErrors`](../README.md#form-validity-observer-options-default-errors) and/or the browser's default error messages, it _does not_ need to be `configure`d.
 
 The `ReactValidationErrors<M, E>` type is an enhanced version of the core [`ValidationErrors<M, E>`](../types.md#validationerrorsm-e) type. Here is how `ReactValidationErrors` compares to `ValidationErrors`.
 

docs/form-validity-observer/integrations/solid.md

@@ -49,7 +49,7 @@ Remember that `autoObserve` is simply a convenience utility for calling `observe
 
 An enhanced version of [`FormValidityObserver.configure`](../README.md#method-formvalidityobserverconfigureename-string-errormessages-validationerrorsm-e-void) for `Solid`. In addition to configuring a field's error messages, it generates the props that should be applied to the field based on the provided arguments.
 
-> Note: If the field is _only_ using the browser's default error messages, it does _not_ need to be `configure`d.
+> Note: If the field is _only_ using the configured [`defaultErrors`](../README.md#form-validity-observer-options-default-errors) and/or the browser's default error messages, it _does not_ need to be `configure`d.
 
 The `SolidValidationErrors<M, E>` type is an enhanced version of the core [`ValidationErrors<M, E>`](../types.md#validationerrorsm-e) type. Here is how `SolidValidationErrors` compares to `ValidationErrors`.