chore: Minor Improvements/Corrections to Documentation

ITenthusiasm · ITenthusiasm · commit fdd69e4f80ae · 2024-05-04T09:08:29.000-04:00
We missed some of these documentation updates/improvements while
updating our project. Hopefully the docs are better now, though
surely there are other improvements that could be made.
diff --git a/TODO.md b/TODO.md
@@ -2,11 +2,10 @@
 
 ## Priority
 
-- [ ] REVIEW OUR ENTIRE `FormValidityObserver` DOCUMENTATION to make sure it's looking correct. This would include our sub-bullet point below.
-  - [ ] We need to update the `Integration` docs for the `FormValidityObserver`. Our example on how to create one's own integration needs to include the new change where we only use a singular `type` (instead of allowing an array of types).
 - [ ] ALSO deprecate `useFormValidityObserver` in favor of `useMemo(() => createFormValidityObserver())`. We may also want to update the `DESIGN_DECISIONS` docs when we do this.
 - [ ] Release `0.9.0` after doing everything ABOVE this task.
 - [ ] CONSIDER updating `@form-observer/lit` to automatically use `renderByDefault` and Lit's `render` function.
+  - [ ] Alternatively, consider updating our StackBlitz Lit example to have a renderer example and a default-renderer example.
 - [ ] Add docs on how to reconcile error messages between server and client.
   - [ ] Consider doing this AFTER releasing `0.9.0` if you need to.
 
diff --git a/docs/form-validity-observer/README.md b/docs/form-validity-observer/README.md
@@ -299,20 +299,24 @@ Validates all of the observed form's fields, returning `true` if _all_ of the va
 <dl>
   <dt><code>focus</code></dl>
   <dd>
-    <p>Indicates that the <em>first</em> field in the DOM that fails validation should be focused. Defaults to <code>false</code>.</p>
+    <p>
+      Indicates that the <em>first</em> field in the DOM that fails validation should be focused and scrolled into view. Defaults to <code>false</code>.
+    </p>
+    <p>
+      When the <code>focus</code> option is <code>false</code>, you can consider <code>validateFields()</code> to be an enhanced version of <code>form.checkValidity()</code>. When the <code>focus</code> option is <code>true</code>, you can consider <code>validateFields()</code> to be an enhanced version of <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/reportValidity"><code>form.reportValidity()</code></a>.
+    </p>
   </dd>
   <dt><code>enableRevalidation</code></dt>
   <dd>
     <p>
       Enables revalidation for <strong>all</strong> of the form's fields. Defaults to <code>true</code>. (This option is only relevant if a value was provided for the observer's <a href="#form-validity-observer-options-revalidate-on"><code>revalidateOn</code></a> option.)
     </p>
+    <p>
+      Note that the <code>enableRevalidation</code> option can prevent field revalidation from being turned on, but it cannot be used to <em>turn off</em> revalidation.
+    </p>
   </dd>
 </dl>
 
-When the `focus` option is `false`, you can consider `validateFields()` to be an enhanced version of `form.checkValidity()`. When the `focus` option is `true`, you can consider `validateFields()` to be an enhanced version of [`form.reportValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/reportValidity).
-
-Note that the `enableRevalidation` option can prevent field revalidation from being turned on, but it cannot be used to _turn off_ revalidation.
-
 ### Method: `FormValidityObserver.validateField(name: string, options?: ValidateFieldOptions): boolean | Promise<boolean>`
 
 Validates the form field with the specified `name`, returning `true` if the field passes validation and `false` otherwise. The `boolean` that `validateField()` returns will be wrapped in a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) if the field's [`validate` constraint](./types.md#validationerrorsm-e-r) runs asynchronously. This promise will `resolve` after the asynchronous validation function `resolves`. Unlike the [`validateFields()`](#method-formvalidityobservervalidatefieldsoptions-validatefieldsoptions-boolean--promiseboolean) method, this promise will also `reject` if the asynchronous validation function `rejects`.
@@ -330,21 +334,25 @@ Validates the form field with the specified `name`, returning `true` if the fiel
     <p>An object used to configure the <code>validateField()</code> method. The following properties are supported:</p>
     <dl>
       <dt><code>focus</code></dt>
-      <dd>Indicates that the field should be focused if it fails validation. Defaults to <code>false</code>.</dd>
+      <dd>
+        <p>Indicates that the field should be focused and scrolled into view if it fails validation. Defaults to <code>false</code>.
+        <p>
+          When the <code>focus</code> option is <code>false</code>, you can consider <code>validateField()</code> to be an enhanced version of <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity"><code>field.checkValidity()</code></a>. When the <code>focus</code> option is <code>true</code>, you can consider <code>validateField()</code> to be an enhanced version of <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity"><code>field.reportValidity()</code></a>.
+        </p>
+      </dd>
       <dt><code>enableRevalidation</code></dt>
       <dd>
         <p>
           Enables revalidation for the validated field. Defaults to <code>true</code>. (This option is only relevant if a value was provided for the observer's <a href="#form-validity-observer-options-revalidate-on"><code>revalidateOn</code></a> option.)
         </p>
+        <p>
+          Note that the <code>enableRevalidation</code> option can prevent field revalidation from being turned on, but it cannot be used to <em>turn off</em> revalidation.
+        </p>
       </dd>
     </dl>
   </dd>
 </dl>
 
-When the `focus` option is `false`, you can consider `validateField()` to be an enhanced version of [`field.checkValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity). When the `focus` option is `true`, you can consider `validateField()` to be an enhanced version of [`field.reportValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity).
-
-Note that the `enableRevalidation` option can prevent field revalidation from being turned on, but it cannot be used to _turn off_ revalidation.
-
 ### Method: `FormValidityObserver.setFieldError<E>(name: string, message: `[`ErrorMessage<string, E>`](./types.md#errormessagem-e)`|`[`ErrorMessage<M, E>`](./types.md#errormessagem-e)`, render?: boolean): void`
 
 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.
diff --git a/docs/form-validity-observer/integrations/lit.md b/docs/form-validity-observer/integrations/lit.md
@@ -71,7 +71,7 @@ customElements.define("my-form", MyForm);
 
 > Note: If you prefer, you can call `observe` and `unobserve`/`disconnect` manually instead.
 
-## Function: `createFormValidityObserver(types, options)`
+## Function: `createFormValidityObserver(type, options)`
 
 Creates a `FormValidityObserver` whose methods can be safely destructured. It accepts the exact same arguments as the [`FormValidityObserver`'s constructor](../README.md#constructor-formvalidityobservertypes-options). If you don't need to destructure any of the observer's methods, then you are free to use the `FormValidityObserver`'s constructor directly.
 
diff --git a/docs/form-validity-observer/integrations/preact.md b/docs/form-validity-observer/integrations/preact.md
@@ -2,7 +2,7 @@
 
 A _convenience_ API for reducing code repetition in a [Preact](https://preactjs.com/) application using the [`FormValidityObserver`](../README.md).
 
-## Function: `createFormValidityObserver(types, options)`
+## Function: `createFormValidityObserver(type, options)`
 
 Creates an enhanced version of the `FormValidityObserver`, known as the `PreactFormValidityObserver`. It accepts the exact same arguments as the [`FormValidityObserver`'s constructor](../README.md#constructor-formvalidityobservertypes-options).
 
diff --git a/docs/form-validity-observer/integrations/react.md b/docs/form-validity-observer/integrations/react.md
@@ -11,7 +11,7 @@ Additional Topics:
 
 - [`Usage with Class Components`](#usage-with-class-components)
 
-## Function: `createFormValidityObserver(types, options)`
+## Function: `createFormValidityObserver(type, options)`
 
 Creates an enhanced version of the `FormValidityObserver`, known as the `ReactFormValidityObserver`. It accepts the exact same arguments as the [`FormValidityObserver`'s constructor](../README.md#constructor-formvalidityobservertypes-options).
 
diff --git a/docs/form-validity-observer/integrations/solid.md b/docs/form-validity-observer/integrations/solid.md
@@ -2,7 +2,7 @@
 
 A _convenience_ API for reducing code repetition in a [Solid](https://www.solidjs.com/) application using the [`FormValidityObserver`](../README.md).
 
-## Function: `createFormValidityObserver(types, options)`
+## Function: `createFormValidityObserver(type, options)`
 
 Creates an enhanced version of the `FormValidityObserver`, known as the `SolidFormValidityObserver`. It accepts the exact same arguments as the [`FormValidityObserver`'s constructor](../README.md#constructor-formvalidityobservertypes-options).
 
diff --git a/docs/form-validity-observer/integrations/svelte.md b/docs/form-validity-observer/integrations/svelte.md
@@ -2,7 +2,7 @@
 
 A _convenience_ API for reducing code repetition in a [Svelte](https://svelte.dev/) application using the [`FormValidityObserver`](../README.md).
 
-## Function: `createFormValidityObserver(types, options)`
+## Function: `createFormValidityObserver(type, options)`
 
 Creates an enhanced version of the `FormValidityObserver`, known as the `SvelteFormValidityObserver`. It accepts the exact same arguments as the [`FormValidityObserver`'s constructor](../README.md#constructor-formvalidityobservertypes-options).
 
diff --git a/docs/form-validity-observer/integrations/vue.md b/docs/form-validity-observer/integrations/vue.md
@@ -2,7 +2,7 @@
 
 A _convenience_ API for reducing code repetition in a [Vue](https://vuejs.org/) application using the [`FormValidityObserver`](../README.md).
 
-## Function: `createFormValidityObserver(types, options)`
+## Function: `createFormValidityObserver(type, options)`
 
 Creates an enhanced version of the `FormValidityObserver`, known as the `VueFormValidityObserver`. It accepts the exact same arguments as the [`FormValidityObserver`'s constructor](../README.md#constructor-formvalidityobservertypes-options).
 
diff --git a/packages/core/FormValidityObserver.d.ts b/packages/core/FormValidityObserver.d.ts
@@ -105,7 +105,7 @@ export interface FormValidityObserverOptions<
 }
 
 export interface ValidateFieldOptions {
-  /** Indicates that the field should be focused if it fails validation. Defaults to `false`. */
+  /** Indicates that the field should be focused and scrolled into view if it fails validation. Defaults to `false`. */
   focus?: boolean;
   /**
    * Enables revalidation for the validated field. Defaults to `true`.
@@ -115,7 +115,10 @@ export interface ValidateFieldOptions {
 }
 
 export interface ValidateFieldsOptions {
-  /** Indicates that the _first_ field in the DOM that fails validation should be focused. Defaults to `false`. */
+  /**
+   * Indicates that the _first_ field in the DOM that fails validation should be focused and scrolled into view.
+   * Defaults to `false`.
+   */
   focus?: boolean;
   /**
    * Enables revalidation for **all** of the form's fields. Defaults to `true`.
diff --git a/packages/core/FormValidityObserver.js b/packages/core/FormValidityObserver.js
@@ -92,7 +92,8 @@ const attrs = Object.freeze({
 
 /**
  * @typedef {Object} ValidateFieldOptions
- * @property {boolean} [focus] Indicates that the field should be focused if it fails validation. Defaults to `false`.
+ * @property {boolean} [focus] Indicates that the field should be focused and scrolled into view if it fails validation.
+ * Defaults to `false`.
  *
  * @property {boolean} [enableRevalidation] Enables revalidation for the validated field. Defaults to `true`.
  * (This option is only relevant if a value was provided for the observer's
@@ -101,8 +102,8 @@ const attrs = Object.freeze({
 
 /**
  * @typedef {Object} ValidateFieldsOptions
- * @property {boolean} [focus] Indicates that the _first_ field in the DOM that fails validation should be focused.
- * Defaults to `false`.
+ * @property {boolean} [focus] Indicates that the _first_ field in the DOM that fails validation should be focused and
+ * scrolled into view. Defaults to `false`.
  *
  * @property {boolean} [enableRevalidation] Enables revalidation for **all** of the form's fields. Defaults to `true`.
  * (This option is only relevant if a value was provided for the observer's
