chore: Update Documentation for the FormValidityObserver

Note: We technically have not yet updated the types for
the JS framework integrations, so we aren't 100% sure that
our docs in that area are correct yet. But we're pretty
confident that the documentation should be correct.

After reviewing these docs on GitHub and verifying that we
didn't break any links, we'll follow up with the integration
TypeScript changes (and any docs updates that should be
done as a result).

Author: ITenthusiasm

docs/extras/philosophy.md

@@ -318,7 +318,7 @@ The next natural step is to provide a way to validate an _entire form_. For that
 
 If the developer opts out of accessible error messaging, the `setFieldError` and `clearFieldError` methods will fallback to `field.setCustomValidity()`, and `validateField({ focus: true })`/`validateFields({ focus: true })` will fallback to `field.reportValidity()`/`form.reportValidity()`.
 
-As an added bonus, the `FormValidityObserver` exposes a [`configure`](../form-validity-observer/README.md#method-formvalidityobserverconfigureename-string-errormessages-validationerrorsm-e-void) method that enables developers to configure the error messages that should be displayed when a field fails validation. (Any unconfigured error messages will fallback to the `validationMessage` that the browser provides.) It also allows a custom validation function to be configured for the field.
+As an added bonus, the `FormValidityObserver` exposes a [`configure`](../form-validity-observer/README.md#method-formvalidityobserverconfigureename-string-errormessages-validationerrorsm-e-r-void) method that enables developers to configure the error messages that should be displayed when a field fails validation. (Any unconfigured error messages will fallback to the `validationMessage` that the browser provides.) It also allows a custom validation function to be configured for the field.
 
 Seeing the big picture here? The `FormValidityObserver` is basically a wrapper for the browser's native features when accessible error messages aren't being used. When accessible error messages are needed, it functions as an _enhancement_ (not a replacement) of the browser's features to satisfy that need. As a bonus, it includes configurable scrolling/rendering functionality as well.
 

docs/form-validity-observer/README.md

@@ -135,12 +135,14 @@ 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>;
+  R extends boolean = false,
+>(types: T, options?: FormValidityObserverOptions<M, E, R>): SvelteFormValidityObserver<M, R> {
+  const observer = new FormValidityObserver(types, options) as unknown as SvelteFormValidityObserver<M, R>;
   return observer;
 }
 
-interface SvelteFormValidityObserver<M = string> extends Omit<FormValidityObserver<M>, "configure"> {}
+interface SvelteFormValidityObserver<M = string, R extends boolean = false>
+  extends Omit<FormValidityObserver<M, R>, "configure"> {}
 ```
 
 Note: Since we will be augmenting the `FormValidityObserver.configure()` method, we are _not_ copying its type definition to the `SvelteFormValidityObserver` interface.
@@ -162,8 +164,9 @@ 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>;
+  R extends boolean = false,
+>(types: T, options?: FormValidityObserverOptions<M, E, R>): SvelteFormValidityObserver<M, R> {
+  const observer = new FormValidityObserver(types, options) as unknown as SvelteFormValidityObserver<M, R>;
 
   /* ---------- Bindings ---------- */
   // Form Observer Methods
@@ -180,7 +183,8 @@ function createFormValidityObserver<
   return observer;
 }
 
-interface SvelteFormValidityObserver<M = string> extends Omit<FormValidityObserver<M>, "configure"> {}
+interface SvelteFormValidityObserver<M = string, R extends boolean = false>
+  extends Omit<FormValidityObserver<M, R>, "configure"> {}
 ```
 
 Note: Because we will be enhancing the `configure` method, we _have not_ attached it to the `observer` object that we return.
@@ -203,8 +207,9 @@ 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>;
+  R extends boolean = false,
+>(types: T, options?: FormValidityObserverOptions<M, E, R>): SvelteFormValidityObserver<M, R> {
+  const observer = new FormValidityObserver(types, options) as unknown as SvelteFormValidityObserver<M, R>;
 
   /* ---------- Bindings ---------- */
   // Apply all bindings...
@@ -224,7 +229,8 @@ function createFormValidityObserver<
   return observer;
 }
 
-interface SvelteFormValidityObserver<M = string> extends Omit<FormValidityObserver<M>, "configure"> {
+interface SvelteFormValidityObserver<M = string, R extends boolean = false>
+  extends Omit<FormValidityObserver<M, R>, "configure"> {
   autoObserve(form: HTMLFormElement, novalidate?: boolean): ActionReturn;
 }
 ```
@@ -284,15 +290,15 @@ The benefit of this approach, as we mentioned earlier, is that our configuration
 <input {...configure("email", { type: { value: "email", message: "Invalid Email" }, required: true })} />
 ```
 
-Of course, as with the core `FormValidityObserver`, calls to `configure` can be skipped if the developer is _only_ using the browser's default error messages:
+Of course, as with the core `FormValidityObserver`, calls to `configure` can be skipped if the developer is _only_ using the using the configured [`defaultErrors`](../README.md#form-validity-observer-options-default-errors) and/or the browser's default error messages:
 
 ```html
 <input name="email" type="email" required />
 ```
 
 Note: Our `configure` method should _not_ support adding an error `message` for a constraint without the constraint's `value`. This is because the error message would never get used in that scenario.
 
-Now that we've specified all the requirements, let's implement this functionality. First off, we'll update the `SvelteFormValidityObserver` interface. Some new TypeScript types will have to be added here. If you're only using JavaScript, you can skip this part. :&rpar;
+Now that we've specified all of the requirements, let's implement this functionality. First off, we'll update the `SvelteFormValidityObserver` interface. Some new TypeScript types will have to be added here. If you're only using JavaScript, you can skip this part. :&rpar;
 
 #### Adding the TypeScript Types for `configure`
 
@@ -311,9 +317,10 @@ import type { HTMLInputAttributes } from "svelte/elements";
 
 // Definition of `createFormValidityObserver` ...
 
-interface SvelteFormValidityObserver<M = string> extends Omit<FormValidityObserver<M>, "configure"> {
+interface SvelteFormValidityObserver<M = string, R extends boolean = false>
+  extends Omit<FormValidityObserver<M, R>, "configure"> {
   // Augments `FormValidityObserver.configure()`
-  configure<E extends ValidatableField>(name: string, errorMessages: SvelteValidationErrors<M, E>): SvelteFieldProps;
+  configure<E extends ValidatableField>(name: string, errorMessages: SvelteValidationErrors<M, E, R>): SvelteFieldProps;
   autoObserve(form: HTMLFormElement, novalidate?: boolean): ActionReturn;
 }
 
@@ -324,23 +331,30 @@ type SvelteFieldProps = Pick<
 >;
 
 // Augments `ValidationErrors` type
-export interface SvelteValidationErrors<M, E extends ValidatableField = ValidatableField>
-  extends Pick<ValidationErrors<M, E>, "badinput" | "validate"> {
-  required?: SvelteErrorDetails<M, HTMLInputAttributes["required"], E> | ErrorMessage<string, E>;
-  minlength?: SvelteErrorDetails<M, HTMLInputAttributes["minlength"], E>;
-  min?: SvelteErrorDetails<M, HTMLInputAttributes["min"], E>;
-  maxlength?: SvelteErrorDetails<M, HTMLInputAttributes["maxlength"], E>;
-  max?: SvelteErrorDetails<M, HTMLInputAttributes["max"], E>;
-  step?: SvelteErrorDetails<M, HTMLInputAttributes["step"], E>;
-  type?: SvelteErrorDetails<M, HTMLInputAttributes["type"], E>;
-  pattern?: SvelteErrorDetails<M, HTMLInputAttributes["pattern"], E>;
+export interface SvelteValidationErrors<M, E extends ValidatableField = ValidatableField, R extends boolean = false>
+  extends Pick<ValidationErrors<M, E, R>, "badinput" | "validate"> {
+  required?:
+    | SvelteErrorDetails<M, HTMLInputAttributes["required"], E, R>
+    | ErrorMessage<R extends true ? M : string, E>;
+  minlength?: SvelteErrorDetails<M, HTMLInputAttributes["minlength"], E, R>;
+  min?: SvelteErrorDetails<M, HTMLInputAttributes["min"], E, R>;
+  maxlength?: SvelteErrorDetails<M, HTMLInputAttributes["maxlength"], E, R>;
+  max?: SvelteErrorDetails<M, HTMLInputAttributes["max"], E, R>;
+  step?: SvelteErrorDetails<M, HTMLInputAttributes["step"], E, R>;
+  type?: SvelteErrorDetails<M, HTMLInputAttributes["type"], E, R>;
+  pattern?: SvelteErrorDetails<M, HTMLInputAttributes["pattern"], E, R>;
 }
 
 // Augments `ErrorDetails` type
-type SvelteErrorDetails<M, V, E extends ValidatableField = ValidatableField> =
+type SvelteErrorDetails<M, V, E extends ValidatableField = ValidatableField, R extends boolean = false> =
   | V
-  | { render: true; message: ErrorMessage<M, E>; value: V }
-  | { render?: false; message: ErrorMessage<string, E>; value: V };
+  | (R extends true
+      ?
+          | { render?: true; message: ErrorMessage<M, E>; value: V }
+          | { render: false; message: ErrorMessage<string, E>; value: V }
+      :
+          | { render: true; message: ErrorMessage<M, E>; value: V }
+          | { render?: false; message: ErrorMessage<string, E>; value: V });
 ```
 
 You don't have to understand what these types do to use them. But if you're interested in understanding what's happening here, let's walk you through what we did.
@@ -349,7 +363,7 @@ You don't have to understand what these types do to use them. But if you're inte
 
 Our `configure` method has changed the type of the `errorMessages` argument from `ValidationErrors` to `SvelteValidationErrors` so that we can configure a field's constraints and error messages simultaneously. The type that enables us to support this feature is `SvelteErrorDetails`.
 
-`SvelteErrorDetails` is _almost_ the exact same type as [`ErrorDetails`](../types.md#errordetailsm-e). There are only two differences between `SvelteErrorDetail` and `ErrorDetails`:
+`SvelteErrorDetails` is _almost_ the exact same type as [`ErrorDetails`](../types.md#errordetailsm-e-r). There are only two differences between `SvelteErrorDetails` and `ErrorDetails`:
 
 <ol>
   <li>
@@ -362,19 +376,19 @@ Our `configure` method has changed the type of the `errorMessages` argument from
   </li>
   <li>
     <p>
-      When an object is <em>not</em> being used, <code>SvelteErrorDetails</code> details replaces <code>ErrorMessage&lt;string&gt;</code> with <code>V</code>, where <code>V</code> represents the value of the constraint. This is an <em>alteration</em> of the <code>ErrorDetails</code> type.
+      When an object is <em>not</em> being used, <code>SvelteErrorDetails</code> details replaces <code>ErrorMessage</code> with <code>V</code>, where <code>V</code> represents the value of the constraint. This is an <em>alteration</em> of the <code>ErrorDetails</code> type.
     </p>
     <p>
-      Whenever a raw value is used for <code>SvelteErrorDetails</code>, developers will be able to specify a field's constraint <em>without</em> providing the error message for that constraint. In this scenario, the browser's default error message will be used for that constraint instead. Since it does not make sense to provide an error message without a constraint value,  the <code>SvelteErrorDetails</code> type does not support that "use case".
+      Whenever a raw value is used for <code>SvelteErrorDetails</code>, developers will be able to specify a field's constraint <em>without</em> providing the error message for that constraint. In this scenario, the browser's default error message (or the configured <a href="../README.md#form-validity-observer-options-default-errors">default error</a>) will be used for that constraint instead. Since it does not make sense to provide an error message without a constraint value,  the <code>SvelteErrorDetails</code> type does not support that "use case".
     </p>
   </li>
 </ol>
 
-Just as the `ErrorDetails` type forms the foundation of the [`ValidationErrors`](../types.md#validationerrorsm-e) type, so the `SvelteErrorDetails` type forms the foundation of the `SvelteValidationErrors` type. The type definition for `SvelteValidationErrors` is _almost_ the exact same as the type definition for `ValidationErrors`. In fact, the `badinput` and `validate` properties are exactly the same between the 2.
+Just as the `ErrorDetails` type forms the foundation of the [`ValidationErrors`](../types.md#validationerrorsm-e-r) type, so the `SvelteErrorDetails` type forms the foundation of the `SvelteValidationErrors` type. The type definition for `SvelteValidationErrors` is _almost_ the exact same as the type definition for `ValidationErrors`. In fact, the `badinput` and `validate` properties are exactly the same between the 2.
 
 The primary way in which the `SvelteValidationErrors` type differs from the `ValidationErrors` type is that it takes constraint values into account (with the help of `SvelteErrorDetails`). It determines the value types that each constraint supports by looking at `Svelte`'s type definition for the `input` field's props (i.e., `HTMLInputAttributes`). (**Note: If you're using a different JS framework, you should use _that_ framework's type definitions for the `input` field's props instead.**)
 
-Notice that the `required` constraint is slightly different from the others in that it supports one additional type: [`ErrorMessage<string>`](../types.md#errormessagem-e). If the developer supplies an error message by itself for the `required` constraint, it is safe to assume that `required` is `true`. This is an assumption that can only be made safely with the `required` constraint because it is a `boolean`.
+Notice that the `required` constraint is slightly different from the others in that it supports one additional type: [`ErrorMessage`](../types.md#errormessagem-e). If the developer supplies an error message by itself for the `required` constraint, it is safe to assume that `required` is `true`. This is an assumption that can only be made safely with the `required` constraint because it is a `boolean`.
 
 ##### Enhancing the Return Type of `configure`
 
@@ -390,8 +404,9 @@ type SvelteFieldProps = Pick<
 And we make _this_ the return type of `configure`:
 
 ```ts
-interface SvelteFormValidityObserver<M = string> extends Omit<FormValidityObserver<M>, "configure"> {
-  configure<E extends ValidatableField>(name: string, errorMessages: SvelteValidationErrors<M, E>): SvelteFieldProps;
+interface SvelteFormValidityObserver<M = string, R extends boolean = false>
+  extends Omit<FormValidityObserver<M, R>, "configure"> {
+  configure<E extends ValidatableField>(name: string, errorMessages: SvelteValidationErrors<M, E, R>): SvelteFieldProps;
   autoObserve(form: HTMLFormElement, novalidate?: boolean): ActionReturn;
 }
 ```
@@ -409,23 +424,24 @@ 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>;
+  R extends boolean = false,
+>(types: T, options?: FormValidityObserverOptions<M, E, R>): SvelteFormValidityObserver<M, R> {
+  const observer = new FormValidityObserver(types, options) as unknown as SvelteFormValidityObserver<M, R>;
 
   /* ---------- Bindings ---------- */
   // Apply bindings for exposed methods ...
 
   /** **Private** reference to the original {@link FormValidityObserver.configure} method */
-  const originalConfigure = observer.configure.bind(observer) as FormValidityObserver<M>["configure"];
+  const originalConfigure = observer.configure.bind(observer) as FormValidityObserver<M, R>["configure"];
 
   /* ---------- Enhancements ---------- */
   // Definition for `autoObserver` ...
 
   // Enhanced `configure` method
   observer.configure = (name, errorMessages) => {
-    const keys = Object.keys(errorMessages) as Array<keyof SvelteValidationErrors<M>>;
+    const keys = Object.keys(errorMessages) as Array<keyof SvelteValidationErrors<M, ValidatableField, R>>;
     const props = { name } as SvelteFieldProps;
-    const config = {} as ValidationErrors<M>;
+    const config = {} as ValidationErrors<M, ValidatableField, R>;
 
     // Build `props` object and error `config` object from `errorMessages`
     for (let i = 0; i < keys.length; i++) {
@@ -516,9 +532,9 @@ If we want to keep our code readable, then the next best solution is to use `any
 
 ```ts
 observer.configure = (name, errorMessages) => {
-  const keys = Object.keys(errorMessages) as Array<keyof SvelteValidationErrors<M>>;
+  const keys = Object.keys(errorMessages) as Array<keyof SvelteValidationErrors<M, ValidatableField, R>>;
   const props = { name } as SvelteFieldProps;
-  const config = {} as ValidationErrors<M>;
+  const config = {} as ValidationErrors<M, ValidatableField, R>;
 
   // Build `props` object and error `config` object from `errorMessages`
   for (let i = 0; i < keys.length; i++) {