chore: Clarify Why We Need Manual .d.ts Files for Our Child Classes

We forgot about these limitations... And because we forgot about these
limitations, we ran off and tried to remove the `FormStorageObserver.d.ts`
and `FormValidityObserver.d.ts` files... But then we saw the problems
that came up when TypeScript attempted to generate these files automatically
from the JS files... We're not interested in enduring that headache again.

Note that even if we remove generic constructors from the
`FormStorageObserver` and the `FormValidityObserver`, TypeScript will still
get confused.

We've further documented why we're stuck in this predicament, and we hope
the TypeScript team will pull through for us at some point.

Author: ITenthusiasm

packages/core/FormStorageObserver.d.ts

@@ -3,6 +3,24 @@
  * See:
  * - https://github.com/microsoft/TypeScript/issues/55919 (generic constructors)
  * - https://github.com/microsoft/TypeScript/issues/40451 (generic constructors)
+ *
+ * Note: Although the `FormStorageObserver` doesn't necessarily need a generic constructor, we can't
+ * rely on the JS file just yet. The reason for this is that we're still dependent on `FormObserver.d.ts`
+ * to provide type information that consumers can use (until _true_ generic constructors are _hopefully_ supported in
+ * the future). And since the `FormObserver` name is being exposed in 2 ways (as an `interface` _and_ a `constructor`),
+ * TypeScript gets confused when it sees something like `FormStorageObserver extends FormObserver`. (For clarity,
+ * TypeScript's confusion happens for the `.d.ts` file that it generates. It has no problem with the JS file itself.)
+ * So... We're stuck doing some extra TypeScript dancing for the `FormStorageObserver`. And sadly, that will more or
+ * less be the case until generic constructors are figured out by the TypeScript team. At least, that's our
+ * current understanding.
+ *
+ * Note that even if we remove generic constructors from the `FormStorageObserver` and the `FormValidityObserver`,
+ * TypeScript will still get confused. This is because having a single name (`FormObserver`) for 2 entities is
+ * still confusing for TypeScript when the `extends` keyword comes into play.
+ *
+ * So DON'T run off and try to replace this file with the pure JS file. That won't work because TypeScript gets confused
+ * when it generates the `.d.ts` files from the JS files. If TypeScript ever allows JS files to be a source of types,
+ * that might be another thing that could help us here besides TypeScript supporting generic constructors...
  */
 import type FormObserver from "./FormObserver.js";
 import type { EventType, OneOrMany } from "./types.d.ts";

packages/core/FormValidityObserver.d.ts

@@ -3,6 +3,24 @@
  * See:
  * - https://github.com/microsoft/TypeScript/issues/55919 (generic constructors)
  * - https://github.com/microsoft/TypeScript/issues/40451 (generic constructors)
+ *
+ * Note: Although the `FormValidityObserver` doesn't necessarily need a generic constructor, we can't
+ * rely on the JS file just yet. The reason for this is that we're still dependent on `FormObserver.d.ts`
+ * to provide type information that consumers can use (until _true_ generic constructors are _hopefully_ supported in
+ * the future). And since the `FormObserver` name is being exposed in 2 ways (as an `interface` _and_ a `constructor`),
+ * TypeScript gets confused when it sees something like `FormValidityObserver extends FormObserver`. (For clarity,
+ * TypeScript's confusion happens for the `.d.ts` file that it generates. It has no problem with the JS file itself.)
+ * So... We're stuck doing some extra TypeScript dancing for the `FormValidityObserver`. And sadly, that will more or
+ * less be the case until generic constructors are figured out by the TypeScript team. At least, that's our
+ * current understanding.
+ *
+ * Note that even if we remove generic constructors from the `FormStorageObserver` and the `FormValidityObserver`,
+ * TypeScript will still get confused. This is because having a single name (`FormObserver`) for 2 entities is
+ * still confusing for TypeScript when the `extends` keyword comes into play.
+ *
+ * So DON'T run off and try to replace this file with the pure JS file. That won't work because TypeScript gets confused
+ * when it generates the `.d.ts` files from the JS files. If TypeScript ever allows JS files to be a source of types,
+ * that might be another thing that could help us here besides TypeScript supporting generic constructors...
  */
 import type { EventType, ValidatableField } from "./types.d.ts";