@goodie-forms/core 1.0.0-alpha

package/src/form/FormController.ts

@@ -0,0 +1,290 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { enableArrayMethods, enableMapSet, produce } from "immer";
+import { createNanoEvents } from "nanoevents";
+import { Field } from "../form/Field";
+import { DeepPartial } from "../types/DeepPartial";
+import { removeBy } from "../utils/removeBy";
+import { FormField } from "./FormField";
+
+enableMapSet();
+enableArrayMethods();
+
+export namespace Form {
+  export type Status = "idle" | "validating" | "submitting";
+
+  export type FormConfigs<TShape extends object> = ConstructorParameters<
+    typeof FormController<TShape>
+  >[0];
+
+  export interface PreventableEvent {
+    preventDefault(): void;
+  }
+
+  export type SubmitSuccessHandler<
+    TShape extends object,
+    TEvent extends PreventableEvent,
+  > = (
+    data: TShape,
+    event: TEvent,
+    abortSignal: AbortSignal,
+  ) => void | Promise<void>;
+
+  export type SubmitErrorHandler<TEvent extends PreventableEvent> = (
+    issues: StandardSchemaV1.Issue[],
+    event: TEvent,
+    abortSignal: AbortSignal,
+  ) => void | Promise<void>;
+}
+
+export class FormController<TShape extends object = object> {
+  _status: Form.Status = "idle";
+  _fields = new Map<Field.Paths<TShape>, FormField<TShape, any>>();
+  _initialData: DeepPartial<TShape>;
+  _data: DeepPartial<TShape>;
+  _issues: StandardSchemaV1.Issue[] = [];
+
+  equalityComparators?: Record<any, (a: any, b: any) => boolean>;
+  validationSchema?: StandardSchemaV1<TShape, TShape>;
+
+  public readonly events = createNanoEvents<{
+    statusChanged(newStatus: Form.Status, oldStatus: Form.Status): void;
+    fieldBound(fieldPath: Field.Paths<TShape>): void;
+    fieldUnbound(fieldPath: Field.Paths<TShape>): void;
+    fieldTouchUpdated(path: Field.Paths<TShape>): void;
+    fieldDirtyUpdated(path: Field.Paths<TShape>): void;
+    elementBound(fieldPath: Field.Paths<TShape>, el: HTMLElement): void;
+    elementUnbound(fieldPath: Field.Paths<TShape>): void;
+    validationTriggered(fieldPath: Field.Paths<TShape>): void;
+    validationIssuesUpdated(fieldPath: Field.Paths<TShape>): void;
+    valueChanged(
+      path: Field.Paths<TShape>,
+      newValue: Field.GetValue<TShape, Field.Paths<TShape>> | undefined,
+      oldValue: Field.GetValue<TShape, Field.Paths<TShape>> | undefined,
+    ): void;
+  }>();
+
+  constructor(config: {
+    initialData?: DeepPartial<TShape>;
+    validationSchema?: StandardSchemaV1<TShape, TShape>;
+    equalityComparators?: Record<any, (a: any, b: any) => boolean>;
+  }) {
+    this.validationSchema = config.validationSchema;
+    this.equalityComparators = config.equalityComparators;
+    this._initialData = config.initialData ?? ({} as DeepPartial<TShape>);
+    this._data = produce(this._initialData, () => {});
+  }
+
+  get isDirty() {
+    for (const field of this._fields.values()) {
+      if (field.isDirty) return true;
+    }
+    return false;
+  }
+
+  get isValid() {
+    return this._issues.length === 0;
+  }
+
+  get isSubmitting() {
+    return this._status === "submitting";
+  }
+
+  protected setStatus(newStatus: Form.Status) {
+    if (newStatus === this._status) return;
+    const oldStatus = this._status;
+    this._status = newStatus;
+    this.events.emit("statusChanged", newStatus, oldStatus);
+  }
+
+  _unsafeSetFieldValue<TPath extends Field.Paths<TShape>>(
+    path: TPath,
+    value: Field.GetValue<TShape, TPath>,
+    config?: { updateInitialValue?: boolean },
+  ) {
+    if (config?.updateInitialValue) {
+      this._initialData = produce(this._initialData, (draft) => {
+        Field.setValue<TShape, TPath>(draft as TShape, path, value);
+      });
+    }
+    this._data = produce(this._data, (draft) => {
+      Field.setValue<TShape, TPath>(draft as TShape, path, value);
+    });
+  }
+
+  bindField<TPath extends Field.Paths<TShape>>(
+    path: TPath,
+    config?: {
+      defaultValue?: Field.GetValue<TShape, TPath>;
+      domElement?: HTMLElement;
+    },
+  ) {
+    const field = new FormField(this, path);
+
+    console.log("Binding", path, config?.defaultValue, field.id);
+    this._fields.set(path, field);
+    this.events.emit("fieldBound", path);
+
+    if (config?.defaultValue != null) {
+      this._unsafeSetFieldValue(path, config.defaultValue, {
+        updateInitialValue: true,
+      });
+    }
+
+    if (config?.domElement != null) {
+      field.bindElement(config.domElement);
+    }
+
+    return field;
+  }
+
+  unbindField(path: Field.Paths<TShape>) {
+    this._fields.delete(path);
+    this.events.emit("fieldUnbound", path);
+  }
+
+  // TODO: Add an option to keep dirty/touched fields as they are
+  reset(newInitialData?: DeepPartial<TShape>) {
+    this.setStatus("idle");
+    this._data = this._initialData;
+    this._issues = [];
+
+    for (const field of this._fields.values()) {
+      field.reset();
+    }
+
+    if (newInitialData != null) {
+      this._initialData = newInitialData;
+      this._data = produce(this._initialData, () => {});
+    }
+  }
+
+  getField<TPath extends Field.Paths<TShape>>(
+    path: TPath,
+    config: { bindIfMissing: true },
+  ): FormField<TShape, TPath>;
+  getField<TPath extends Field.Paths<TShape>>(
+    path: TPath,
+  ): FormField<TShape, TPath> | undefined;
+  getField<TPath extends Field.Paths<TShape>>(
+    path: TPath,
+    config?: { bindIfMissing?: boolean },
+  ) {
+    let field = this._fields.get(path);
+
+    if (field == null && config?.bindIfMissing) {
+      field = this.bindField(path);
+    }
+
+    return field;
+  }
+
+  clearFieldIssues<TPath extends Field.Paths<TShape>>(path: TPath) {
+    this._issues = this._issues.filter((issue) => {
+      if (issue.path == null) return true;
+      const issuePath = issue.path.join(".");
+      return issuePath !== path;
+    });
+  }
+
+  private async applyValidation<TPath extends Field.Paths<TShape>>(
+    _result: StandardSchemaV1.Result<TShape>,
+    path: TPath,
+  ) {
+    const diff = Field.diff(
+      this._issues,
+      _result.issues ?? [],
+      Field.deepEqual,
+      (issue) => {
+        if (issue.path == null) return false;
+        const issuePath = issue.path.join(".");
+        return issuePath === path;
+      },
+    );
+
+    removeBy(this._issues, (issue) => diff.removed.includes(issue));
+
+    diff.added.forEach((issue) => this._issues.push(issue));
+
+    if (diff.added.length !== 0 || diff.removed.length !== 0) {
+      this.events.emit("validationIssuesUpdated", path);
+    }
+  }
+
+  async validateField<TPath extends Field.Paths<TShape>>(path: TPath) {
+    if (this._status !== "idle") return;
+
+    if (this.validationSchema == null) return;
+
+    this.setStatus("validating");
+
+    this.getField(path, { bindIfMissing: true });
+
+    const result = await this.validationSchema["~standard"].validate(
+      this._data,
+    );
+
+    this.events.emit("validationTriggered", path);
+    this.applyValidation(result, path);
+
+    this.setStatus("idle");
+  }
+
+  async validateForm() {
+    if (this._status !== "idle") return;
+
+    if (this.validationSchema == null) return;
+
+    this.setStatus("validating");
+
+    const result = await this.validationSchema["~standard"].validate(
+      this._data,
+    );
+
+    for (const path of this._fields.keys()) {
+      this.events.emit("validationTriggered", path);
+      this.applyValidation(result, path);
+    }
+
+    // Append non-registered issues too
+    const diff = Field.diff(this._issues, result.issues ?? [], Field.deepEqual);
+    diff.added.forEach((issue) => this._issues.push(issue));
+
+    this.setStatus("idle");
+  }
+
+  createSubmitHandler<TEvent extends Form.PreventableEvent>(
+    onSuccess?: Form.SubmitSuccessHandler<TShape, TEvent>,
+    onError?: Form.SubmitErrorHandler<TEvent>,
+  ) {
+    return async (event: TEvent) => {
+      if (event != null) {
+        event.preventDefault();
+      }
+
+      if (this._status !== "idle") return;
+
+      const abortController = new AbortController();
+
+      await this.validateForm();
+
+      if (this._issues.length === 0) {
+        this.setStatus("submitting");
+        await onSuccess?.(this._data as TShape, event, abortController.signal);
+        this.setStatus("idle");
+        return;
+      }
+
+      for (const issue of this._issues) {
+        if (issue.path == null) continue;
+        const fieldPath = issue.path.join(".") as Field.Paths<TShape>;
+        const field = this.getField(fieldPath);
+        if (field == null) continue;
+        if (field.boundElement == null) continue;
+        field.focus();
+        break;
+      }
+      await onError?.(this._issues, event, abortController.signal);
+      this.setStatus("idle");
+    };
+  }
+}

package/src/form/FormField.ts

@@ -0,0 +1,199 @@
+import { immerable, produce } from "immer";
+import { getId } from "../utils/getId";
+import { Field } from "./Field";
+import { FormController } from "./FormController";
+
+export class FormField<
+  TShape extends object,
+  TPath extends Field.Paths<TShape>,
+> {
+  public readonly id = getId();
+
+  protected target?: HTMLElement;
+
+  protected _isTouched = false;
+  protected _isDirty = false;
+
+  constructor(
+    public readonly controller: FormController<TShape>,
+    public readonly path: TPath,
+  ) {}
+
+  get value() {
+    return Field.getValue<TShape, TPath>(
+      this.controller._data as TShape,
+      this.path,
+    );
+  }
+
+  get boundElement() {
+    return this.target;
+  }
+
+  get issues() {
+    return this.controller._issues.filter(
+      (issue) => issue.path?.join(".") === this.path,
+    );
+  }
+
+  get isTouched() {
+    return this._isTouched;
+  }
+
+  get isDirty() {
+    return this._isDirty;
+  }
+
+  get isValid() {
+    return this.issues.length === 0;
+  }
+
+  protected _setTouched(isTouched: boolean) {
+    const changed = this._isTouched !== isTouched;
+    this._isTouched = isTouched;
+    if (changed) this.controller.events.emit("fieldTouchUpdated", this.path);
+  }
+
+  protected _setDirty(isDirty: boolean) {
+    const changed = this._isDirty !== isDirty;
+    this._isDirty = isDirty;
+    if (changed) this.controller.events.emit("fieldDirtyUpdated", this.path);
+  }
+
+  bindElement(el: HTMLElement | undefined) {
+    if (el != null) this.controller.events.emit("elementBound", this.path, el);
+    else this.controller.events.emit("elementUnbound", this.path);
+    this.target = el;
+  }
+
+  protected static ensureImmerability(value: any) {
+    if (typeof value !== "object" || value === null) return;
+
+    // Skip plain objects
+    const proto = Object.getPrototypeOf(value);
+    if (proto === Object.prototype || proto === null) return;
+
+    const ctor = proto.constructor;
+    if (typeof ctor !== "function") return;
+
+    // Skip known built-ins
+    if (
+      value instanceof Date ||
+      value instanceof RegExp ||
+      value instanceof Map ||
+      value instanceof Set ||
+      value instanceof WeakMap ||
+      value instanceof WeakSet ||
+      ArrayBuffer.isView(value)
+    ) {
+      return;
+    }
+
+    if (ctor[immerable] === true) return;
+
+    // Define non-enumerable immerable flag
+    ctor[immerable] = true;
+  }
+
+  setValue(
+    value: Field.GetValue<TShape, TPath>,
+    opts?: Parameters<typeof this.modifyValue>[1],
+  ) {
+    return this.modifyValue(() => value, opts);
+  }
+
+  modifyValue(
+    modifier: (
+      currentValue: Field.GetValue<TShape, TPath>,
+      field: this,
+    ) => Field.GetValue<TShape, TPath> | void,
+    opts?: {
+      shouldTouch?: boolean;
+      shouldMarkDirty?: boolean;
+    },
+  ) {
+    if (opts?.shouldTouch == null || opts?.shouldTouch) {
+      this.touch();
+    }
+
+    const initialValue = Field.getValue<TShape, TPath>(
+      this.controller._initialData as TShape,
+      this.path,
+    );
+
+    const oldValue = Field.getValue<TShape, TPath>(
+      this.controller._data as TShape,
+      this.path,
+    );
+
+    FormField.ensureImmerability(initialValue);
+    FormField.ensureImmerability(oldValue);
+
+    this.controller._data = produce(this.controller._data, (draft) => {
+      Field.modifyValue<TShape, TPath>(draft as TShape, this.path, (oldValue) =>
+        modifier(oldValue, this),
+      );
+    });
+
+    const newValue = Field.getValue<TShape, TPath>(
+      this.controller._data as TShape,
+      this.path,
+    );
+
+    FormField.ensureImmerability(newValue);
+
+    const compareCustom = (a: any, b: any) => {
+      if (typeof a !== "object") return;
+      if (typeof b !== "object") return;
+      const ctorA = a.constructor;
+      const ctorB = b.constructor;
+      if (ctorA !== ctorB) return;
+      return this.controller.equalityComparators?.[ctorA]?.(a, b);
+    };
+
+    const valueChanged = !Field.deepEqual(oldValue, newValue, compareCustom);
+
+    if (valueChanged) {
+      this.controller.events.emit(
+        "valueChanged",
+        this.path,
+        newValue,
+        oldValue,
+      );
+    }
+
+    if (opts?.shouldMarkDirty == null || opts?.shouldMarkDirty) {
+      const gotDirty = !Field.deepEqual(initialValue, newValue, compareCustom);
+      this._setDirty(gotDirty);
+    }
+  }
+
+  reset() {
+    this._setTouched(false);
+    this._setDirty(false);
+  }
+
+  touch() {
+    this._setTouched(true);
+  }
+
+  markDirty() {
+    this.touch();
+    this._setDirty(true);
+  }
+
+  triggerValidation() {
+    this.controller.validateField(this.path);
+  }
+
+  focus(opts?: { shouldTouch?: boolean }) {
+    if (opts?.shouldTouch == null || opts.shouldTouch) {
+      this.target?.addEventListener("focus", () => this.touch(), {
+        once: true,
+      });
+    }
+
+    this.target?.scrollIntoView();
+    this.target?.focus();
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./form/Field";
+export * from "./form/FormField";
+export * from "./form/FormController";

package/src/types/DeepPartial.ts

@@ -0,0 +1,3 @@
+export type DeepPartial<T extends object> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};

package/src/utils/getId.ts

@@ -0,0 +1,5 @@
+let id = 0;
+
+export function getId() {
+  return id++;
+}

package/src/utils/removeBy.ts

@@ -0,0 +1,11 @@
+export function removeBy<T>(arr: T[], predicate: (item: T) => boolean) {
+  let indices: number[] = [];
+
+  for (let i = arr.length - 1; i >= 0; i--) {
+    if (predicate(arr[i])) {
+      indices.push(i);
+    }
+  }
+
+  indices.forEach((i) => arr.splice(i, 1));
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "vite";
+
+import dts from "vite-plugin-dts";
+
+export default defineConfig({
+  plugins: [dts()],
+  build: {
+    lib: {
+      entry: "src/index.ts",
+      formats: ["es"],
+      fileName: "index",
+    },
+    rollupOptions: {
+      external: [],
+    },
+    sourcemap: true,
+  },
+});