diff --git a/TODO.md b/TODO.md index c43b018..28beaae 100644 --- a/TODO.md +++ b/TODO.md @@ -2,6 +2,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? diff --git a/docs/form-validity-observer/README.md b/docs/form-validity-observer/README.md index 3c17ce5..75dd96b 100644 --- a/docs/form-validity-observer/README.md +++ b/docs/form-validity-observer/README.md @@ -116,6 +116,17 @@ The `FormValidityObserver()` constructor creates a new observer and configures i The renderer defaults to a function that accepts error messages of type string and renders them to the DOM as raw HTML.

+
defaultErrors: ValidationErrors<M, E>
+
+

+ Configures the default error messages to display for the validation constraints. (See the configure method for more details about error message configuration, and refer to the ValidationErrors type for more details about validation constraints.) +

+

+

+ Note: The defaultErrors.validate option will provide a default custom validation function for all fields in your form. 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 Zod). See Getting the Most out of the defaultErrors Option for examples on how to use this option effectively. +
+

+
@@ -204,11 +215,11 @@ form1.elements[0].dispatchEvent(new FocusEvent("focusout")); // Does nothing ### Method: `FormValidityObserver.configure(name: string, errorMessages: `[`ValidationErrors`](./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 diff --git a/docs/form-validity-observer/guides.md b/docs/form-validity-observer/guides.md index 0f1ceac..cea97b8 100644 --- a/docs/form-validity-observer/guides.md +++ b/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 +
+ + + + + + + + + + + + + + +``` + +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 (`" 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 `