@goodie-forms/core 1.2.5-alpha → 1.3.0

package/src/form/FormController.spec.ts

@@ -0,0 +1,55 @@
+import { expect, test } from "vitest";
+import { FormController } from "../form/FormController";
+
+interface User {
+  name: string;
+  address: {
+    city: string;
+    street: string;
+  };
+  friends: {
+    name: string;
+    tags: string[];
+  }[];
+  coords: [100, 200 | 201];
+}
+
+test("registers fields", () => {
+  const formController = new FormController<User>({});
+
+  let changeInvoked = 0;
+
+  formController.events.on("fieldValueChanged", () => changeInvoked++);
+
+  const path1 = formController.path.of((data) => data.friends[0].tags[99]);
+  expect(formController.getField(path1)).toBeUndefined();
+  const field1 = formController.registerField(path1, { defaultValue: "Tag99" });
+  expect(field1.value).toBe("Tag99");
+  expect(field1.initialValue).toBeUndefined();
+
+  const path2 = formController.path.of("coords[1]");
+  expect(formController.getField(path2)).toBeUndefined();
+  const field2 = formController.registerField(path2);
+  expect(field2.value).toBeUndefined();
+  expect(field2.initialValue).toBeUndefined();
+
+  field1.setValue("Tag100");
+  field2.setValue(200);
+
+  const path3 = formController.path.of("coords");
+  expect(formController.getField(path3)).toBeUndefined();
+  const field3 = formController.registerField(path3, {
+    defaultValue: [100, 200],
+    overrideInitialValue: true,
+  });
+  expect(field3.value).toEqual([undefined, 200]);
+  expect(field3.initialValue).toBeUndefined();
+
+  field3.modifyValue((val) => {
+    val[0] = 100;
+    val[1]++;
+  });
+
+  expect(field3.value).toStrictEqual([100, 201]);
+  expect(changeInvoked).toBe(5);
+});

package/src/form/FormController.ts

@@ -3,9 +3,10 @@ import { produce } from "immer";
 import { createNanoEvents } from "nanoevents";
 import { FieldPath } from "../field/FieldPath";
 import { FieldPathBuilder } from "../field/FieldPathBuilder";
-import { Reconsile } from "../field/Reconcile";
+import { Reconcile } from "../field/Reconcile";
 import { FormField } from "../form/FormField";
-import { DeepPartial } from "../types/DeepPartial";
+import { DeepPartial, DeepReadonly } from "../types/DeepHelpers";
+import { Suppliable, supply } from "../types/Suppliable";
 import { ensureImmerability } from "../utils/ensureImmerability";
 import { removeBy } from "../utils/removeBy";
 
@@ -13,7 +14,7 @@ export namespace FormController {
   export type Configs<TOutput extends object> = {
     initialData?: DeepPartial<TOutput>;
     validationSchema?: StandardSchemaV1<unknown, TOutput>;
-    equalityComparators?: Record<any, (a: any, b: any) => boolean>;
+    equalityComparators?: Map<any, (a: any, b: any) => boolean>;
   };
 
   export interface PreventableEvent {
@@ -22,45 +23,62 @@ export namespace FormController {
 
   export type SubmitSuccessHandler<
     TOutput extends object,
-    TEvent extends PreventableEvent,
-  > = (
-    data: TOutput,
-    event: TEvent,
-    abortSignal: AbortSignal,
-  ) => void | Promise<void>;
-
-  export type SubmitErrorHandler<TEvent extends PreventableEvent> = (
-    issues: StandardSchemaV1.Issue[],
-    event: TEvent,
-    abortSignal: AbortSignal,
-  ) => void | Promise<void>;
+    TEvent extends PreventableEvent | null | undefined,
+  > = (data: DeepReadonly<TOutput>, event: TEvent) => void | Promise<void>;
+
+  export type SubmitErrorHandler<
+    TEvent extends PreventableEvent | null | undefined,
+  > = (issues: StandardSchemaV1.Issue[], event: TEvent) => void | Promise<void>;
 }
 
 export class FormController<TOutput extends object> {
-  _isValidating = false;
-  _isSubmitting = false;
+  private _isValidating = false;
+  private _isSubmitting = false;
+  private _triedSubmitting = false;
+
+  private pathBuilder = new FieldPathBuilder<TOutput>();
 
+  /** @internal use `this.getFields` instead */
   _fields = new Map<string, FormField<TOutput, any>>();
+  /** @internal use `this.initialData` instead */
   _initialData: DeepPartial<TOutput>;
+  /** @internal use `this.data` instead */
   _data: DeepPartial<TOutput>;
+  /** @internal use `this.issues` instead */
   _issues: StandardSchemaV1.Issue[] = [];
 
-  equalityComparators?: Record<any, (a: any, b: any) => boolean>;
+  equalityComparators?: Map<any, (a: any, b: any) => boolean>;
   validationSchema?: StandardSchemaV1<unknown, TOutput>;
 
   public readonly events = createNanoEvents<{
+    /** Emitted when `this.isSubmitting` changes */
     submissionStatusChange(isSubmitting: boolean): void;
+    /** Emitted when `this.isValidating` changes */
     validationStatusChange(isValidating: boolean): void;
 
-    fieldBound(fieldPath: FieldPath.Segments): void;
-    fieldUnbound(fieldPath: FieldPath.Segments): void;
+    /** Emitted when a field is registered */
+    fieldRegistered(fieldPath: FieldPath.Segments): void;
+    /** Emitted when a field is unregistered */
+    fieldUnregistered(fieldPath: FieldPath.Segments): void;
+    /** Emitted when a field's `isTouched` changes */
     fieldTouchUpdated(path: FieldPath.Segments): void;
+    /** Emitted when a field's `isDirty` changes */
     fieldDirtyUpdated(path: FieldPath.Segments): void;
+    /** Emitted when a field's `issues` changes */
     fieldIssuesUpdated(fieldPath: FieldPath.Segments): void;
+    /** Emitted when a field's `reset()` is invoked */
+    fieldReset(fieldPath: FieldPath.Segments): void;
+
+    /** Emitted when a HTMLELement is bound to a field */
     elementBound(fieldPath: FieldPath.Segments, el: HTMLElement): void;
+    /** Emitted when a HTMLELement is unbound from a field */
     elementUnbound(fieldPath: FieldPath.Segments): void;
-    validationTriggered(fieldPath: FieldPath.Segments): void;
-    valueChanged(
+
+    /** Emitted when validation is triggered on a field */
+    fieldValidationTriggered(fieldPath: FieldPath.Segments): void;
+
+    /** Emitted when a field's `value` is updated */
+    fieldValueChanged(
       fieldPath: FieldPath.Segments,
       newValue: {} | undefined,
       oldValue: {} | undefined,
@@ -74,6 +92,22 @@ export class FormController<TOutput extends object> {
     this._data = produce(this._initialData, () => {});
   }
 
+  get data(): DeepReadonly<DeepPartial<TOutput>> {
+    return this._data;
+  }
+
+  get initialData(): DeepReadonly<DeepPartial<TOutput>> {
+    return this._initialData;
+  }
+
+  get issues(): readonly StandardSchemaV1.Issue[] {
+    return this._issues;
+  }
+
+  get path() {
+    return this.pathBuilder;
+  }
+
   get isDirty() {
     for (const field of this._fields.values()) {
       if (field.isDirty) return true;
@@ -82,8 +116,7 @@ export class FormController<TOutput extends object> {
   }
 
   get isValid() {
-    // TODO: Does it still count valid while validating?
-    return this._issues.length === 0;
+    return this.isValidating || this._issues.length === 0;
   }
 
   get isValidating() {
@@ -94,6 +127,10 @@ export class FormController<TOutput extends object> {
     return this._isSubmitting;
   }
 
+  get triedSubmitting() {
+    return this._triedSubmitting;
+  }
+
   protected setValidating(newStatus: boolean) {
     if (this._isValidating === newStatus) return;
     this._isValidating = newStatus;
@@ -106,85 +143,106 @@ export class FormController<TOutput extends object> {
     this.events.emit("submissionStatusChange", newStatus);
   }
 
-  _unsafeSetFieldValue<TPath extends FieldPath.Segments>(
-    path: TPath,
-    value: FieldPath.Resolve<TOutput, TPath>,
-    config?: { updateInitialValue?: boolean },
-  ) {
-    ensureImmerability(value);
-
-    if (config?.updateInitialValue === true) {
-      this._initialData = produce(this._initialData, (draft) => {
-        FieldPath.setValue(draft as TOutput, path, value);
-      });
-    }
-
-    this._data = produce(this._data, (draft) => {
-      FieldPath.setValue(draft as TOutput, path, value);
-    });
-  }
-
-  // TODO: Rename to "register" ??
-  bindField<TPath extends FieldPath.Segments>(
+  registerField<TPath extends FieldPath.Segments>(
     path: TPath,
     config?: {
-      defaultValue?: FieldPath.Resolve<TOutput, TPath>;
-      domElement?: HTMLElement;
+      /**
+       * Used to set value at **path** in **data**, if it's missing.
+       */
+      defaultValue?: Suppliable<FieldPath.Resolve<TOutput, TPath>>;
+      /**
+       * Whether value in **initialData** should also be changed, if **defaultValue** is used or not
+       *
+       * If this is set to `true` and **defaultValue** is used; **initialData** will be modified
+       */
       overrideInitialValue?: boolean;
     },
   ) {
     let currentValue = FieldPath.getValue(this._data as TOutput, path);
 
     if (currentValue == null && config?.defaultValue != null) {
-      this._unsafeSetFieldValue(path, config.defaultValue, {
-        updateInitialValue: config.overrideInitialValue,
+      const defaultValue = supply(config.defaultValue);
+
+      ensureImmerability(defaultValue);
+
+      if (config?.overrideInitialValue === true) {
+        this._initialData = produce(this._initialData, (draft) => {
+          FieldPath.setValue(draft as TOutput, path, defaultValue);
+        });
+      }
+
+      this._data = produce(this._data, (draft) => {
+        FieldPath.setValue(draft as TOutput, path, defaultValue);
       });
+
       currentValue = FieldPath.getValue(this._data as TOutput, path);
     }
 
     const initialValue = FieldPath.getValue(this._initialData as TOutput, path);
 
-    const valueChanged = !Reconsile.deepEqual(currentValue, initialValue);
+    const valueChanged = !Reconcile.deepEqual(currentValue, initialValue);
 
-    const field = new FormField(this, path, {
+    const field = new FormField(this, path, config?.defaultValue, {
       isDirty: valueChanged,
     });
 
-    if (config?.domElement != null) {
-      field.bindElement(config.domElement);
-    }
-
     this._fields.set(field.stringPath, field);
-    this.events.emit("fieldBound", field.path);
+    this.events.emit("fieldRegistered", field.path);
 
     if (valueChanged) {
-      this.events.emit("valueChanged", field.path, currentValue, initialValue);
+      this.events.emit(
+        "fieldValueChanged",
+        field.path,
+        currentValue,
+        initialValue,
+      );
     }
 
     return field as FormField<TOutput, FieldPath.Resolve<TOutput, TPath>>;
   }
 
-  unbindField(path: FieldPath.Segments) {
+  unregisterField(path: FieldPath.Segments) {
     const stringPath = FieldPath.toStringPath(path);
+
+    if (!this._fields.has(stringPath)) return false;
+
     this._fields.delete(stringPath);
-    this.events.emit("fieldUnbound", path);
+    this.events.emit("fieldUnregistered", path);
+    return true;
   }
 
-  // TODO: Add an option to keep dirty/touched fields as they are
   reset(newInitialData?: DeepPartial<TOutput>) {
-    this._data = this._initialData;
-    this._issues = [];
+    const newData = newInitialData ?? this._initialData;
+
+    const fieldUpdates = [] as [FieldPath.Segments, any, any][];
 
     for (const field of this._fields.values()) {
+      const currentValue = FieldPath.getValue(this._data, field.path);
+      const nextValue = FieldPath.getValue(newData, field.path);
+
+      if (!Reconcile.deepEqual(currentValue, nextValue)) {
+        fieldUpdates.push([field.path, nextValue, currentValue]);
+      }
+
       field.reset();
     }
 
     if (newInitialData != null) {
-      this._initialData = newInitialData;
-      this._data = produce(this._initialData, () => {});
+      this._initialData = produce(newInitialData, () => {});
     }
+
+    this._data = produce(newData, () => {});
+    this._issues = [];
+    this._triedSubmitting = false;
+
+    fieldUpdates.forEach(([path, newValue, oldValue]) => {
+      this.events.emit("fieldValueChanged", path, newValue, oldValue);
+    });
   }
 
+  // TODO: resetGracefully(newInitialData?: DeepPartial<TOutput>)
+  // TODO: ^ Keeps dirty/touched fields as they are
+
   getAscendantFields<TPath extends FieldPath.Segments>(path: TPath) {
     const paths = path.map((_, i) => {
       return path.slice(0, i + 1);
@@ -200,6 +258,10 @@ export class FormController<TOutput extends object> {
       | undefined;
   }
 
+  getFields() {
+    return this._fields.values();
+  }
+
   clearFieldIssues<TPath extends FieldPath.Segments>(path: TPath) {
     this._issues = this._issues.filter((issue) => {
       return !FieldPath.equals(FieldPath.normalize(issue.path), path);
@@ -210,11 +272,9 @@ export class FormController<TOutput extends object> {
     _result: StandardSchemaV1.Result<TOutput>,
     path: TPath,
   ) {
-    const diff = Reconsile.diff(
-      this._issues,
-      _result.issues ?? [],
-      Reconsile.deepEqual,
-      (issue) => {
+    const diff = Reconcile.arrayDiff(this._issues, _result.issues ?? [], {
+      equals: Reconcile.deepEqual,
+      include: (issue) => {
         if (issue.path == null) return false;
         const issuePath = FieldPath.normalize(issue.path);
         return (
@@ -222,7 +282,7 @@ export class FormController<TOutput extends object> {
           FieldPath.isDescendant(path, issuePath)
         );
       },
-    );
+    });
 
     removeBy(this._issues, (issue) => diff.removed.includes(issue));
 
@@ -233,54 +293,54 @@ export class FormController<TOutput extends object> {
     }
   }
 
-  async validateField<TPath extends FieldPath.Segments>(path: TPath) {
+  async validateForm() {
     if (this._isValidating) return;
 
     if (this.validationSchema == null) return;
 
     this.setValidating(true);
 
-    if (this.getField(path) == null) this.bindField(path);
-
     const result = await this.validationSchema["~standard"].validate(
       this._data,
     );
 
-    this.events.emit("validationTriggered", path);
-    this.applyValidation(result, path);
+    for (const stringPath of this._fields.keys()) {
+      const path = FieldPath.fromStringPath(stringPath);
+      this.events.emit("fieldValidationTriggered", path);
+      this.applyValidation(result, path);
+    }
+
+    // Append non-registered issues too
+    const diff = Reconcile.arrayDiff(this._issues, result.issues ?? [], {
+      equals: Reconcile.deepEqual,
+    });
+    diff.added.forEach((issue) => this._issues.push(issue));
 
     this.setValidating(false);
   }
 
-  async validateForm() {
+  async validateField<TPath extends FieldPath.Segments>(path: TPath) {
     if (this._isValidating) return;
 
     if (this.validationSchema == null) return;
 
     this.setValidating(true);
 
+    if (this.getField(path) == null) this.registerField(path);
+
     const result = await this.validationSchema["~standard"].validate(
       this._data,
     );
 
-    for (const stringPath of this._fields.keys()) {
-      const path = FieldPath.fromStringPath(stringPath);
-      this.events.emit("validationTriggered", path);
-      this.applyValidation(result, path);
-    }
-
-    // Append non-registered issues too
-    const diff = Reconsile.diff(
-      this._issues,
-      result.issues ?? [],
-      Reconsile.deepEqual,
-    );
-    diff.added.forEach((issue) => this._issues.push(issue));
+    this.events.emit("fieldValidationTriggered", path);
+    this.applyValidation(result, path);
 
     this.setValidating(false);
   }
 
-  createSubmitHandler<TEvent extends FormController.PreventableEvent>(
+  createSubmitHandler<
+    TEvent extends FormController.PreventableEvent | null | undefined,
+  >(
     onSuccess?: FormController.SubmitSuccessHandler<TOutput, TEvent>,
     onError?: FormController.SubmitErrorHandler<TEvent>,
   ) {
@@ -292,14 +352,13 @@ export class FormController<TOutput extends object> {
       if (this._isValidating) return;
       if (this._isSubmitting) return;
 
-      // TODO? impl or cancel
-      const abortController = new AbortController();
+      this._triedSubmitting = true;
 
       await this.validateForm();
 
       if (this._issues.length === 0) {
         this.setSubmitting(true);
-        await onSuccess?.(this._data as TOutput, event, abortController.signal);
+        await onSuccess?.(this._data as any as DeepReadonly<TOutput>, event);
         this.setSubmitting(false);
         return;
       }
@@ -313,36 +372,8 @@ export class FormController<TOutput extends object> {
         field.focus();
         break;
       }
-      await onError?.(this._issues, event, abortController.signal);
+      await onError?.(this._issues, event);
       this.setSubmitting(false);
     };
   }
 }
-
-/* ---- TESTS ---------------- */
-
-// interface User {
-//   name: string;
-//   address: {
-//     city: string;
-//     street: string;
-//   };
-//   friends: {
-//     name: string;
-//     tags: string[];
-//   }[];
-//   coords: [100, 200];
-// }
-
-// const formController = new FormController<User>({});
-// const fieldPathBuilder = new FieldPathBuilder<User>();
-
-// formController.events.on("valueChanged", (fieldPath, value) => {
-//   //                                                 ^?
-// });
-
-// const path1 = fieldPathBuilder.fromProxy((data) => data.friends[0].tags[99]);
-// const field1 = formController.getField(path1);
-
-// const path2 = fieldPathBuilder.fromStringPath("coords[1]");
-// const field2 = formController.getField(path2);