@goodie-forms/core 1.2.5-alpha → 1.2.6-alpha

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;
@@ -94,6 +128,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 +144,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 +259,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,10 +273,10 @@ export class FormController<TOutput extends object> {
     _result: StandardSchemaV1.Result<TOutput>,
     path: TPath,
   ) {
-    const diff = Reconsile.diff(
+    const diff = Reconcile.arrayDiff(
       this._issues,
       _result.issues ?? [],
-      Reconsile.deepEqual,
+      Reconcile.deepEqual,
       (issue) => {
         if (issue.path == null) return false;
         const issuePath = FieldPath.normalize(issue.path);
@@ -233,54 +296,56 @@ 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 ?? [],
+      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 +357,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 +377,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);

package/src/form/FormField.ts

@@ -1,7 +1,9 @@
-import { produce } from "immer";
+import { Draft, produce } from "immer";
 import { FieldPath } from "../field/FieldPath";
-import { Reconsile } from "../field/Reconcile";
+import { Reconcile } from "../field/Reconcile";
 import { FormController } from "../form/FormController";
+import { DeepReadonly } from "../types/DeepHelpers";
+import { Suppliable, supply } from "../types/Suppliable";
 import { ensureImmerability } from "../utils/ensureImmerability";
 import { getId } from "../utils/getId";
 
@@ -13,9 +15,11 @@ export class FormField<TOutput extends object, TValue> {
   protected _isTouched = false;
   protected _isDirty = false;
 
+  /** @internal register via `FormController::registerField` instead */
   constructor(
     public readonly controller: FormController<TOutput>,
     public readonly path: FieldPath.Segments,
+    public readonly defaultValue?: Suppliable<TValue>,
     initialState?: {
       isTouched?: boolean;
       isDirty?: boolean;
@@ -25,20 +29,16 @@ export class FormField<TOutput extends object, TValue> {
     if (initialState?.isDirty) this._setDirty(true);
   }
 
-  get canonicalPath() {
-    return FieldPath.toCanonicalPath(this.path);
-  }
-
   get stringPath() {
     return FieldPath.toStringPath(this.path);
   }
 
-  get value(): TValue | undefined {
-    return FieldPath.getValue(this.controller._data, this.path);
+  get value(): DeepReadonly<TValue> | undefined {
+    return FieldPath.getValue(this.controller.data, this.path);
   }
 
-  get initialValue(): TValue | undefined {
-    return FieldPath.getValue(this.controller._initialData, this.path);
+  get initialValue(): DeepReadonly<TValue> | undefined {
+    return FieldPath.getValue(this.controller.initialData, this.path);
   }
 
   get boundElement() {
@@ -63,6 +63,16 @@ export class FormField<TOutput extends object, TValue> {
     return this.issues.length === 0;
   }
 
+  ensureDefault(opts?: Parameters<typeof this.modifyData>[1]) {
+    if (this.value == null && this.defaultValue != null) {
+      const defaultValue = supply(this.defaultValue);
+
+      if (defaultValue != null) {
+        this.setValue(defaultValue, opts);
+      }
+    }
+  }
+
   protected _setTouched(isTouched: boolean) {
     const changed = this._isTouched !== isTouched;
     this._isTouched = isTouched;
@@ -92,26 +102,33 @@ export class FormField<TOutput extends object, TValue> {
   }
 
   bindElement(el: HTMLElement | undefined) {
-    this.target = el;
     if (el != null) {
+      this.target = el;
       this.controller.events.emit("elementBound", this.path, el);
     } else {
+      this.unbindElement();
+    }
+  }
+
+  unbindElement() {
+    if (this.target != null) {
+      this.target = undefined;
       this.controller.events.emit("elementUnbound", this.path);
     }
   }
 
-  setValue(value: TValue, opts?: Parameters<typeof this.modifyValue>[1]) {
-    return this.modifyValue(() => value, opts);
+  clearIssues() {
+    return this.controller.clearFieldIssues(this.path);
   }
 
-  modifyValue(
-    modifier: (currentValue: TValue | undefined) => TValue | void,
+  private modifyData(
+    draftConsumer: (draft: Draft<typeof this.controller.data>) => void,
     opts?: {
       shouldTouch?: boolean;
       shouldMarkDirty?: boolean;
     },
-  ): void {
-    if (opts?.shouldTouch == null || opts?.shouldTouch) {
+  ) {
+    if (opts?.shouldTouch == null || opts?.shouldTouch === true) {
       this.touch();
     }
 
@@ -123,11 +140,7 @@ export class FormField<TOutput extends object, TValue> {
     const oldValues = ascendantFields.map((field) => field?.value);
     oldValues.forEach((v) => ensureImmerability(v));
 
-    this.controller._data = produce(this.controller._data, (draft) => {
-      FieldPath.modifyValue(draft as TOutput, this.path, (oldValue) => {
-        return modifier(oldValue);
-      });
-    });
+    this.controller._data = produce(this.controller._data, draftConsumer);
 
     const newValues = ascendantFields.map((field) => field?.value);
     newValues.forEach((v) => ensureImmerability(v));
@@ -138,10 +151,10 @@ export class FormField<TOutput extends object, TValue> {
       const ctorA = a.constructor;
       const ctorB = b.constructor;
       if (ctorA !== ctorB) return;
-      return this.controller.equalityComparators?.[ctorA]?.(a, b);
+      return this.controller.equalityComparators?.get(ctorA)?.(a, b);
     };
 
-    const valueChanged = !Reconsile.deepEqual(
+    const valueChanged = !Reconcile.deepEqual(
       oldValues[oldValues.length - 1],
       newValues[newValues.length - 1],
       compareCustom,
@@ -151,7 +164,7 @@ export class FormField<TOutput extends object, TValue> {
       for (let i = ascendantFields.length - 1; i >= 0; i--) {
         const field = ascendantFields[i];
         this.controller.events.emit(
-          "valueChanged",
+          "fieldValueChanged",
           field.path,
           newValues[i],
           oldValues[i],
@@ -160,7 +173,7 @@ export class FormField<TOutput extends object, TValue> {
     }
 
     if (opts?.shouldMarkDirty == null || opts?.shouldMarkDirty) {
-      const gotDirty = !Reconsile.deepEqual(
+      const gotDirty = !Reconcile.deepEqual(
         initialValues[initialValues.length - 1],
         newValues[newValues.length - 1],
         compareCustom,
@@ -169,9 +182,27 @@ export class FormField<TOutput extends object, TValue> {
     }
   }
 
+  setValue(value: TValue, opts?: Parameters<typeof this.modifyData>[1]) {
+    return this.modifyData((data) => {
+      FieldPath.setValue(data as TOutput, this.path, value as never);
+    }, opts);
+  }
+
+  modifyValue(
+    modifier: (currentValue: TValue) => undefined,
+    opts?: Parameters<typeof this.modifyData>[1],
+  ): void {
+    return this.modifyData((data) => {
+      FieldPath.modifyValue(data as TOutput, this.path, (oldValue) => {
+        modifier(oldValue as TValue);
+      });
+    }, opts);
+  }
+
   reset() {
     this._setTouched(false);
     this._setDirty(false);
+    this.controller.events.emit("fieldReset", this.path);
   }
 
   touch() {
@@ -179,22 +210,24 @@ export class FormField<TOutput extends object, TValue> {
   }
 
   markDirty() {
-    this.touch();
     this._setDirty(true);
   }
 
-  triggerValidation() {
+  validate() {
     this.controller.validateField(this.path);
   }
 
-  focus(opts?: { shouldTouch?: boolean }) {
+  focus(opts?: {
+    shouldTouch?: boolean;
+    scrollOptions?: ScrollIntoViewOptions;
+  }) {
     if (opts?.shouldTouch == null || opts.shouldTouch) {
       this.target?.addEventListener("focus", () => this.touch(), {
         once: true,
       });
     }
 
-    this.target?.scrollIntoView();
+    this.target?.scrollIntoView(opts?.scrollOptions);
     this.target?.focus();
   }
 }

package/src/index.ts

@@ -4,9 +4,9 @@ export * from "./field/Reconcile";
 
 export * from "./form/FormController";
 export * from "./form/FormField";
-export * from "./form/NonullFormField";
 
 export * from "./validation/CustomValidation";
 
-export * from "./types/DeepPartial";
+export * from "./types/DeepHelpers";
+export * from "./types/Suppliable";
 export * from "./types/Mixin";

package/src/types/DeepHelpers.ts

@@ -0,0 +1,15 @@
+export type DeepPartial<T> = {
+  [K in keyof T as T[K] extends (...args: any[]) => any ? K : never]: T[K];
+} & {
+  [K in keyof T as T[K] extends (...args: any[]) => any
+    ? never
+    : K]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+export type DeepReadonly<T> = {
+  [K in keyof T as T[K] extends (...args: any[]) => any ? K : never]: T[K];
+} & {
+  readonly [K in keyof T as T[K] extends (...args: any[]) => any
+    ? never
+    : K]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
+};

package/src/types/FormHelpers.ts

@@ -0,0 +1,13 @@
+import { FormField } from "packages/core/src/form/FormField";
+
+// TODO: Consider
+export type FieldValue<T extends FormField<any, any>> =
+  NonNullable<T> extends { value: infer V } ? NonNullable<V> : never;
+
+// TODO: Move to a proper test file
+// declare const x: FormField<{ a: 1; b: 2 }, number>;
+
+// type X0 = FieldValue<typeof x>;
+// //   ^?
+// type X1 = (typeof x)["value"];
+// //   ^?

package/src/types/Suppliable.ts

@@ -0,0 +1,7 @@
+export type Suppliable<T> = T | (() => T);
+
+export function supply<T>(suppliable: T | (() => T)): T {
+  return typeof suppliable === "function"
+    ? (suppliable as () => T)()
+    : suppliable;
+}