chore: Deprecate useFormValidityObserver React Hook

Originally, this hook seemed like a good idea. But actually, it's
turned out to be something less performant than expected, and
something that's more prone to footgunning than expected. See the
`Design Decisions` document for additional details.

Notice that `react` is still a peer dependency of `@form-observer/react`.
In the future, we might use the React package to spy on the
React version so that we can figure out how to appropriately
generate the `autoObserve` function. If we decide against that,
we can remove the peer dependency. Again, see the `Design Decisions`
document for additional details.

Author: ITenthusiasm

TODO.md

@@ -2,7 +2,6 @@
 
 ## Priority
 
-- [ ] 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.

docs/extras/design-decisions.md

@@ -12,6 +12,85 @@ 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-05-04
+
+### Deprecate the `useFormValidityObserver` React Hook
+
+Originally, we thought that it would be a good idea to memoize the `FormValidityObserver` for the React developers who would use our tool. That was the idea behind our `useFormValidityObserver` hook: It would enable developers to use the `FormValidityObserver` without having to think about memoization. It's a great idea! And when possible, I think that maintainers should take this route! But unfortunately, this approach is not always an option...
+
+Consider a scenario where a developer uses the `useFormValidityObserver` hook with a complex configuration:
+
+```tsx
+import { useFormValidityObserver } from "@form-observer/react";
+
+function MyForm() {
+  const { configure, ...rest } = useFormValidityObserver("focusout", {
+    revalidateOn: "input",
+    renderer(errorContainer, errorMessage) {
+      // Implementation ...
+    },
+    defaultErrors: {
+      // Default error message configuration ...
+    },
+  });
+}
+```
+
+The result returned by `useFormValidityObserver` is memoized. However, the `useMemo` hook (which the function calls internally) uses the function's `type` argument and object options as its dependencies. If the `MyForm` component re-renders for any reason, the `"focusout"` and `"input"` strings will remain constant. But the `renderer` function and the `defaultErrors` object will be re-defined during re-renders, causing the `useMemo` hook to create a new `FormValidityObserver`. So those options need to be memoized.
+
+```tsx
+import { useMemo, useCallback } from "react";
+import { useFormValidityObserver } from "@form-observer/react";
+
+function MyForm() {
+  const { configure, ...rest } = useFormValidityObserver("focusout", {
+    revalidateOn: "input",
+    renderer: useCallback((errorContainer, errorMessage) => {
+      // Implementation
+    }, []),
+    defaultErrors: useMemo(
+      () => ({
+        // ... Default error message configuration
+      }),
+      [],
+    ),
+  });
+}
+```
+
+As you can see, this code becomes very ugly very quickly. Even worse, _the code becomes less performant_. Why? Well, because memoization comes with a cost. And the more that memoization is used, the more costs users will have to pay. Yes, memoization is helpful. Yes, under the right circumstances, memoization can bring performance benefits. But it should be used as little as possible and only where it's truly needed.
+
+Here in our example, we're performing 3 memoizations for a single function call. (One for `defaultErrors`, one for `renderer`, and one for `useFormValidityObserver`'s internal call to `useMemo`.) That's not good. A better solution is to memoize the entire result once. But wait... Couldn't we just do that with `createFormValidityObserver`?
+
+```tsx
+import { useMemo } from "react";
+import { createFormValidityObserver } from "@form-observer/react";
+
+function MyForm() {
+  const { configure, ...rest } = useMemo(() => {
+    return createFormValidityObserver("focusout", {
+      revalidateOn: "input",
+      renderer(errorContainer, errorMessage) {
+        // Implementation
+      },
+      defaultErrors: {
+        // ... Default error message configuration
+      },
+    });
+  }, []);
+}
+```
+
+In fact, this is _more performant_ than `useFormValidityObserver`! If we memoize the result from `useFormValidityObserver`, then we perform _2_ memoizations. (One for `useFormValidityObserver`'s internal call to `useMemo`, and one for _our own_ call to `useMemo` on the function's result). But if we simply memoize the result of `createFormValidityObserver` directly, then we only have to perform _1_ memoization.
+
+What does all of this mean? Well... It means that by default, even in the most ideal scenario, `useFormValidityObserver` will never be more performant than calling `useMemo` on `createFormValidityObserver` directly. And in most cases, `useFormValidityObserver` will be _less_ performant. Moreover, many developers won't even be aware of the concerns that we've discussed so far; so they're much more likely to footgun themselves if they use the flashy `useFormValidityObserver` hook!
+
+We wanted to find a way to protect developers from `useMemo`, but we couldn't. (And honestly, no developer who wants to be skilled with React can avoid learning about `useMemo` in this day and age -- not until React Forget stabilizes, at least.) This dilemma is just an unavoidable downside of how React decides to operate as a framework, and we sadly can't do anything to fix that. What we _can_ do is guide developers on how to use `createFormValidityObserver` in React easily and performantly. And that's exactly what we've decided to do instead: Add clearer documentation as a better alternative.
+
+Thankfully, things really aren't that complicated. People just need to wrap `createFormValidityObserver` inside `useMemo` (when using functional components). That's it.
+
+Sidenote: Although we're removing the `useFormValidityObserver` hook, we aren't removing React as a peer dependency [yet]. The reason for this is that we're trying to figure out how to prepare for [React 19's changes to ref callbacks](https://react.dev/blog/2024/04/25/react-19#cleanup-functions-for-refs) (for the sake of `autoObserve`), and we're debating using the React package to help us with this. For example, we could use the React package to tell us the React version being used. Then, we could return one kind of `autoObserve` function if the React version is less than 19, and return a different kind of `autoObserve` function if the React version is greater than or equal to 19. But maybe that's a bad idea? Maybe we should just maintain different versions of our `@form-observer/react` package? Then again, it might not be a bad idea either since it seems like `import { version } from "react"` is [permitted](https://github.com/facebook/react/blob/main/packages/react/index.js#L78) (at least as of today). We'll see...
+
 ## 2024-04-28
 
 ### Only Allow One (1) Event Type to Be Passed to the `FormValidityObserver` Constructor

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

@@ -2,21 +2,10 @@
 
 A _convenience_ API for reducing code repetition in a [React](https://react.dev/) application using the [`FormValidityObserver`](../README.md).
 
-Utilities:
-
-- [`createFormValidityObserver`](#function-createformvalidityobservertypes-options)
-- [`useFormValidityObserver`](#custom-hook-useformvalidityobservertypes-options)
-
-Additional Topics:
-
-- [`Usage with Class Components`](#usage-with-class-components)
-
 ## 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).
 
-This function acts as the foundation for the [`useFormValidityObserver`](#custom-hook-useformvalidityobservertypes-options) hook. For those using class components, you can use `createFormValidityObserver` directly.
-
 ### Return Type: `ReactFormValidityObserver<M, R>`
 
 An enhanced version of the `FormValidityObserver`, designed specifically for React applications. It has the same Type Parameters as the `FormValidityObserver`. As with the `FormValidityObserver`, the type of `M` is derived from the [`renderer`](../README.md#form-validity-observer-options-renderer) option, and the type of `R` is derived from the [`renderByDefault`](../README.md#form-validity-observer-options-render-by-default) option.
@@ -220,34 +209,35 @@ function MyForm() {
 
 The return type of `configure` is simply an object containing the props that should be applied to the configured field. In addition to the field's `name`, this object will include any validation props that were configured by the function (e.g., `required`, `minLength`, `maxLength`, `pattern`, etc.).
 
-## Custom Hook: `useFormValidityObserver(types, options)`
+## Gotchas: Remember to Memoize Your Observer Instance(s) When Necessary
+
+As we mentioned previously, React has a unique re-rendering model. Whenever a state change happens in a React functional component, _the entire component function_ is re-run. If you're instantiating classes (such as the `FormValidityObserver`) in the body of your component's function, then React may re-instantiate the class during a re-render -- even if you don't want that to happen. Sometimes this can lead to inconsistent/unexpected outcomes.
 
-A custom React Hook that creates an enhanced version of the `FormValidityObserver` and [memoizes](https://react.dev/reference/react/useMemo) its value.
+To circumvent this problem, React provides the [`useMemo`](https://react.dev/reference/react/useMemo) hook. This hook guarantees that a given value will not change or be recalculated between re-renders. (If you ever want the value to be recalculated, you can provide an array of dependencies that indicate when the value should be recalculated. In the case of the `FormValidityObserver`, we only want to instantiate it _once_, so no dependencies are necessary.) Below is an example of how to use `useMemo` with the `createFormValidityObserver` function.
 
 ```tsx
 import { useMemo } from "react";
-import { useFormValidityObserver } from "@form-observer/react";
+import { createFormValidityObserver } from "@form-observer/react";
 
 function MyForm() {
-  const { autoObserve, configure } = useFormValidityObserver("focusout");
-
-  return (
-    // If your component does not re-render, you don't need to memoize `autoObserve`'s return value.
-    <form ref={useMemo(autoObserve, [autoObserve])}>
-      <input {...configure("first-name", { required: "We need to know who you are!" })} />
-    </form>
-  );
+  const { autoObserve, configure } = useMemo(() => createFormValidityObserver("focusout"), []);
+  return <form ref={useMemo(autoObserve, [])}>{/* Form Fields */}</form>;
 }
 ```
 
-The purpose of the memoization is two-fold:
+Note: If you are using React's ESLint Rules for hooks, the linter will sometimes tell you to list invalid/unnecessary dependencies for `useMemo`. For example, in the code above, ESLint may tell you to list `autoObserve` as a dependency for the 2nd call to `useMemo`. But because the call to `createFormValidityObserver` is memoized, the `autoObserve` value will never change. Consequently, the 2nd call to `useMemo` should have no dependencies at all.
+
+You can choose to disable the ESLint rule in cases like this one where the rule is incorrect, or you can explicitly list the dependency like so:
+
+```tsx
+<form ref={useMemo(autoObserve, [autoObserve])}>{/* Form Fields */}</form>
+```
 
-1. When the component employing `useFormValidityObserver` re-renders (whether due to state changes or prop updates), the memoization prevents the observer from being re-created/reset. (This is likely not a practical concern if `configure` is only used inside your component's returned JSX.)
-2. Because the outputs of `useFormValidityObserver` are memoized, they won't cause unnecessary re-renders in [memoized children](https://react.dev/reference/react/memo), nor will they cause or unnecessary function re-runs in hooks that depend on them (such as `useEffect`, `useCallback`, and custom hooks that have dependency arrays).
+Since `autoObserve` will never change, the `useMemo` hook will never run any recalculations when `autoObserve` is passed as a dependency. So in the end, you're free to decide how to handle your lint warnings in these situations -- whether by appeasing the linter or by disabling it locally.
 
-If you don't need to worry about these scenarios, then you are free to use [`createFormValidityObserver`](#function-createformvalidityobservertypes-options) instead; it will give you the exact same result (unmemoized). If you _do_ need to worry about these scenarios, then bear in mind that **the observer will be recreated whenever the arguments to the hook change, whether by value _or_ by reference**.
+If you know that a functional component using `createFormValidityObserver` will never re-render, then you can ditch the `useMemo` hook entirely. For more details on memoization, see React's documentation on [`useMemo`](https://react.dev/reference/react/useMemo) and [`memo`](https://react.dev/reference/react/memo). You can also read [_When to useMemo and useCallback_](https://kentcdodds.com/blog/usememo-and-usecallback) by Kent C. Dodds.
 
-Note that this is a very small hook created solely for your convenience. If you want, you can use `useMemo` directly to wrap any calls to `createFormValidityObserver` instead. For more details on memoization, see React's documentation on [`useMemo`](https://react.dev/reference/react/useMemo) and [`memo`](https://react.dev/reference/react/memo). You can also read [_When to useMemo and useCallback_](https://kentcdodds.com/blog/usememo-and-usecallback) by Kent C. Dodds.
+> Note: For those using class components, "memoization" happens automatically as long as the observer is created only once (i.e., during the class's construction).
 
 ## Usage with Class Components
 

packages/preact/README.md

@@ -29,10 +29,10 @@ Here's an example of how to automatically validate your form fields when a user
 
 ```jsx
 import { useMemo } from "preact/hooks";
-import { useFormValidityObserver } from "@form-observer/preact";
+import { createFormValidityObserver } from "@form-observer/preact";
 
 function MyForm() {
-  const { autoObserve, configure, validateFields } = useFormValidityObserver("focusout");
+  const { autoObserve, configure, validateFields } = useMemo(() => createFormValidityObserver("focusout"), []);
 
   function handleSubmit(event) {
     event.preventDefault();

packages/react/README.md

@@ -29,10 +29,10 @@ Here's an example of how to automatically validate your form fields when a user
 
 ```jsx
 import { useMemo } from "react";
-import { useFormValidityObserver } from "@form-observer/react";
+import { createFormValidityObserver } from "@form-observer/react";
 
 function MyForm() {
-  const { autoObserve, configure, validateFields } = useFormValidityObserver("focusout");
+  const { autoObserve, configure, validateFields } = useMemo(() => createFormValidityObserver("focusout"), []);
 
   function handleSubmit(event) {
     event.preventDefault();
@@ -128,7 +128,7 @@ class MyForm extends Component {
 }
 ```
 
-For more details on what `createFormValidityObserver` and `useFormValidityObserver` can do (like custom validation, manual error handling, and more), see our [documentation](https://github.com/enthusiastic-js/form-observer/blob/main/docs/form-validity-observer/integrations/react.md).
+For more details on what `createFormValidityObserver` can do (like custom validation, manual error handling, and more), see our [documentation](https://github.com/enthusiastic-js/form-observer/blob/main/docs/form-validity-observer/integrations/react.md).
 
 ## Other Uses
 

packages/react/__tests__/useFormValidityObserver.test.ts

@@ -1,4 +1,3 @@
 export * from "@form-observer/core";
 export { default as createFormValidityObserver } from "./createFormValidityObserver.js";
-export { default as useFormValidityObserver } from "./useFormValidityObserver.js";
 export type * from "./types.d.ts";

packages/react/index.d.ts

@@ -1,3 +1,2 @@
 export * from "@form-observer/core";
 export { default as createFormValidityObserver } from "./createFormValidityObserver.js";
-export { default as useFormValidityObserver } from "./useFormValidityObserver.js";

packages/react/index.js

@@ -21,14 +21,6 @@
       "types": "./createFormValidityObserver.d.ts",
       "default": "./createFormValidityObserver.js"
     },
-    "./useFormValidityObserver": {
-      "require": {
-        "types": "./useFormValidityObserver.d.cts",
-        "default": "./useFormValidityObserver.cjs"
-      },
-      "types": "./useFormValidityObserver.d.ts",
-      "default": "./useFormValidityObserver.js"
-    },
     "./types": {
       "require": {
         "types": "./types.d.cts"