oxform-core 0.1.0

package/src/form-context-api.ts

@@ -0,0 +1,232 @@
+import { defaultMeta, defaultStatus } from '#field-api.constants';
+import type {
+  FieldMeta,
+  FormBaseStore,
+  FormIssue,
+  FormOptions,
+  FormStore,
+  PersistedFieldMeta,
+  PersistedFormStatus,
+  ValidateOptions,
+} from '#form-api.types';
+import type { DeepKeys } from '#more-types';
+import type { StandardSchema } from '#types';
+import { get } from '#utils/get';
+import { validate } from '#utils/validate';
+import { Derived, Store } from '@tanstack/store';
+import { isDeepEqual, isFunction, mergeDeep, stringToPath } from 'remeda';
+
+export class FormContextApi<
+  Schema extends StandardSchema,
+  Values extends StandardSchema.InferInput<Schema> = StandardSchema.InferInput<Schema>,
+  Field extends DeepKeys<Values> = DeepKeys<Values>,
+> {
+  public options!: FormOptions<Schema>;
+  public persisted: Store<FormBaseStore<Schema>>;
+  public store!: Derived<FormStore<Schema>>;
+
+  constructor(options: FormOptions<Schema>) {
+    const values = mergeDeep(options.defaultValues as never, options.values ?? {}) as Values;
+
+    this.options = options;
+
+    this.persisted = new Store<FormBaseStore<Schema>>({
+      values,
+      fields: {},
+      refs: {},
+      status: defaultStatus,
+      errors: {},
+    });
+
+    this.store = new Derived<FormStore<Schema>>({
+      deps: [this.persisted],
+      fn: ({ currDepVals }) => {
+        const persisted = currDepVals[0] as FormBaseStore<Schema>;
+
+        const invalid = Object.values(persisted.errors).some(issues => issues.length > 0);
+        const dirty = Object.values(persisted.fields).some(meta => meta.dirty);
+        const fields = Object.fromEntries(
+          Object.entries(persisted.fields).map(([key, meta]) => {
+            return [key, this.buildFieldMeta(key, meta, persisted.values as Values, persisted.errors)];
+          }),
+        );
+
+        return {
+          ...persisted,
+          fields,
+          status: {
+            ...persisted.status,
+            submitted: persisted.status.submits > 0,
+            valid: !invalid,
+            dirty: persisted.status.dirty || dirty,
+          },
+        };
+      },
+    });
+  }
+
+  public get status() {
+    return this.store.state.status;
+  }
+
+  public get values() {
+    return this.store.state.values;
+  }
+
+  private get validator() {
+    const store = this.store.state;
+    const validate = this.options.validate;
+
+    return {
+      change: isFunction(validate?.change) ? validate.change(store) : validate?.change,
+      submit: isFunction(validate?.submit) ? validate.submit(store) : (validate?.submit ?? this.options.schema),
+      blur: isFunction(validate?.blur) ? validate.blur(store) : validate?.blur,
+      focus: isFunction(validate?.focus) ? validate.focus(store) : validate?.focus,
+    };
+  }
+
+  public buildFieldMeta = (
+    fieldName: string,
+    persistedMeta: PersistedFieldMeta | undefined,
+    values: Values,
+    errors: Record<string, FormIssue[]>,
+  ): FieldMeta => {
+    const path = stringToPath(fieldName);
+    const value = get(values as never, path);
+    const defaultValue = get(this.options.defaultValues, path);
+    const invalid = errors[fieldName]?.length > 0;
+    const baseMeta = persistedMeta ?? defaultMeta;
+
+    return {
+      ...baseMeta,
+      default: isDeepEqual(value, defaultValue),
+      pristine: !baseMeta.dirty,
+      valid: !invalid,
+    } satisfies FieldMeta;
+  };
+
+  public setFieldMeta = (name: string, meta: Partial<PersistedFieldMeta>) => {
+    this.persisted.setState(current => {
+      return {
+        ...current,
+        fields: {
+          ...current.fields,
+          [name]: {
+            ...defaultMeta,
+            ...this.persisted.state.fields[name],
+            ...meta,
+          },
+        },
+      };
+    });
+  };
+
+  public resetFieldMeta = (name: string) => {
+    this.persisted.setState(current => {
+      const fields = { ...current.fields };
+      const all = Object.keys(current.fields);
+      const affected = all.filter(key => key.startsWith(name));
+
+      for (const key of affected) {
+        delete fields[key];
+      }
+
+      return {
+        ...current,
+        fields,
+      };
+    });
+  };
+
+  public recomputeFieldMeta = (name: string) => {
+    this.persisted.setState(current => {
+      const related: string[] = this.options.related?.[name as never] ?? [];
+      const all = Object.keys(current.fields);
+      const affected = all.filter(key => key.startsWith(name) || related.includes(key));
+      const updated = affected.reduce(
+        (acc, key) => {
+          return {
+            ...acc,
+            [key]: this.buildFieldMeta(key, current.fields[key], current.values as Values, current.errors),
+          };
+        },
+        {} as Record<string, FieldMeta>,
+      );
+
+      return {
+        ...current,
+        fields: {
+          ...current.fields,
+          ...updated,
+        },
+      };
+    });
+  };
+
+  public setStatus = (status: Partial<PersistedFormStatus>) => {
+    this.persisted.setState(current => {
+      return {
+        ...current,
+        status: {
+          ...current.status,
+          ...status,
+        },
+      };
+    });
+  };
+
+  public validate = async (field?: Field | Field[], options?: ValidateOptions) => {
+    const validator = options?.type ? this.validator[options.type] : this.options.schema;
+
+    if (!validator) return [];
+
+    this.setStatus({ validating: true });
+
+    const { issues: allIssues } = await validate(validator, this.store.state.values);
+
+    if (!allIssues) {
+      this.persisted.setState(current => {
+        return { ...current, errors: {}, status: { ...current.status, validating: false } };
+      });
+
+      return [];
+    }
+
+    const fields = field ? (Array.isArray(field) ? field : [field]) : undefined;
+    const related: string[] = fields?.flatMap(field => this.options.related?.[field as never] ?? []) ?? [];
+    const affected = [...(fields ?? []), ...related];
+
+    const issues = allIssues.filter(issue => {
+      const path = issue.path?.join('.') ?? 'root';
+      return !fields || affected.some(key => path.startsWith(key));
+    });
+
+    const errors = issues.reduce((acc, issue) => {
+      const path = issue.path?.join('.') ?? 'root';
+      return {
+        ...acc,
+        [path]: [...(acc[path] ?? []), issue],
+      };
+    }, {} as any);
+
+    this.persisted.setState(current => {
+      const existing = { ...current.errors };
+
+      for (const key of affected) {
+        delete existing[key];
+      }
+
+      return {
+        ...current,
+        errors: {
+          ...(fields ? existing : {}), // when validating a specific set of fields, keep the existing errors
+          ...errors,
+        },
+      };
+    });
+
+    this.setStatus({ validating: false });
+
+    return issues;
+  };
+}

package/src/form-field-api.ts

@@ -0,0 +1,174 @@
+import { defaultMeta } from '#field-api.constants';
+import type { FieldChangeOptions, FormIssue, FormResetFieldOptions, FormSetErrorsOptions } from '#form-api.types';
+import type { FormContextApi } from '#form-context-api';
+import type { DeepKeys, DeepValue } from '#more-types';
+import type { StandardSchema } from '#types';
+import { get } from '#utils/get';
+import { update, type Updater } from '#utils/update';
+import { batch } from '@tanstack/store';
+import { setPath, stringToPath } from 'remeda';
+
+export class FormFieldApi<
+  Schema extends StandardSchema,
+  Values extends StandardSchema.InferInput<Schema> = StandardSchema.InferInput<Schema>,
+  Field extends DeepKeys<Values> = DeepKeys<Values>,
+> {
+  constructor(private context: FormContextApi<Schema>) {}
+
+  /**
+   * Changes the value of a specific field with optional control over side effects.
+   * @param name - The name of the field to change
+   * @param value - The new value to set for the field
+   * @param options - Optional configuration for controlling validation, dirty state, and touched state
+   */
+  public change = <Name extends Field>(
+    name: Name,
+    updater: Updater<DeepValue<Values, Name>>,
+    options?: FieldChangeOptions,
+  ) => {
+    const shouldDirty = options?.should?.dirty !== false;
+    const shouldTouch = options?.should?.touch !== false;
+    const shouldValidate = options?.should?.validate !== false;
+
+    this.context.persisted.setState(current => {
+      const value = get(current.values as never, stringToPath(name)) as DeepValue<Values, Name>;
+
+      const values = setPath(
+        current.values as never,
+        stringToPath(name) as never,
+        update(updater, value) as never,
+      ) as Values;
+
+      return {
+        ...current,
+        values,
+      };
+    });
+
+    if (shouldValidate) void this.context.validate(name, { type: 'change' });
+
+    batch(() => {
+      if (shouldDirty) this.context.setFieldMeta(name, { dirty: true });
+      if (shouldTouch) this.context.setFieldMeta(name, { touched: true });
+    });
+  };
+
+  public focus = <Name extends Field>(name: Name) => {
+    const ref = this.context.store.state.refs[name as never];
+
+    if (ref) ref.focus();
+
+    this.context.setFieldMeta(name as never, { touched: true });
+    void this.context.validate(name as never, { type: 'focus' });
+  };
+
+  public blur = <Name extends Field>(name: Name) => {
+    const ref = this.context.store.state.refs[name as never];
+
+    if (ref) ref.blur();
+
+    this.context.setFieldMeta(name as never, { blurred: true });
+    void this.context.validate(name as never, { type: 'blur' });
+  };
+
+  public get = <Name extends Field>(name: Name) => {
+    return get(this.context.store.state.values as never, stringToPath(name)) as DeepValue<Values, Name>;
+  };
+
+  public meta = <Name extends Field>(name: Name) => {
+    const meta = this.context.store.state.fields[name];
+
+    if (meta) return meta;
+
+    const updated = this.context.buildFieldMeta(
+      name,
+      undefined,
+      this.context.store.state.values as Values,
+      this.context.store.state.errors,
+    );
+
+    this.context.setFieldMeta(name, updated);
+
+    return updated;
+  };
+
+  public register = <Name extends Field>(name: Name) => {
+    return (element: HTMLElement | null) => {
+      if (!element) return;
+
+      this.context.persisted.setState(current => {
+        return {
+          ...current,
+          refs: {
+            ...current.refs,
+            [name]: element,
+          },
+        };
+      });
+    };
+  };
+
+  public errors = <Name extends Field>(name: Name) => {
+    return this.context.store.state.errors[name] ?? [];
+  };
+
+  public setErrors = <Name extends Field>(name: Name, errors: FormIssue[], options?: FormSetErrorsOptions) => {
+    this.context.persisted.setState(current => {
+      const existing = current.errors[name] ?? [];
+      let updated: FormIssue[];
+
+      switch (options?.mode) {
+        case 'append':
+          updated = [...existing, ...errors];
+          break;
+        case 'keep':
+          updated = existing.length > 0 ? existing : errors;
+          break;
+        case 'replace':
+        default:
+          updated = errors;
+          break;
+      }
+
+      return {
+        ...current,
+        errors: {
+          ...current.errors,
+          [name]: updated,
+        },
+      };
+    });
+  };
+
+  public reset = <Name extends Field>(name: Name, options?: FormResetFieldOptions<DeepValue<Values, Name>>) => {
+    const path = stringToPath(name as never);
+    const defaultValue = get(this.context.options.defaultValues, path) as DeepValue<Values, Name>;
+    const value = options?.value ?? defaultValue;
+
+    this.context.persisted.setState(current => {
+      const values = setPath(current.values as never, path as never, value as never);
+      const fields = { ...current.fields };
+      const refs = { ...current.refs };
+      const errors = { ...current.errors };
+
+      if (options?.meta) {
+        const currentMeta = options?.keep?.meta ? (fields[name as string] ?? defaultMeta) : defaultMeta;
+        fields[name as string] = {
+          ...currentMeta,
+          ...options.meta,
+        };
+      } else if (!options?.keep?.meta) delete fields[name as string];
+
+      if (!options?.keep?.refs) delete refs[name as string];
+      if (!options?.keep?.errors) delete errors[name as string];
+
+      return {
+        ...current,
+        values,
+        fields,
+        refs,
+        errors,
+      };
+    });
+  };
+}

package/src/more-types.ts

@@ -0,0 +1,178 @@
+// reference: https://github.com/TanStack/form/blob/main/packages/form-core/src/util-types.ts#L161
+
+/**
+ * @private
+ */
+export type UnwrapOneLevelOfArray<T> = T extends (infer U)[] ? U : T;
+
+type Narrowable = string | number | bigint | boolean;
+
+type NarrowRaw<A> =
+  | (A extends [] ? [] : never)
+  | (A extends Narrowable ? A : never)
+  | {
+      [K in keyof A]: A[K] extends Function ? A[K] : NarrowRaw<A[K]>;
+    };
+
+type Try<A1, A2, Catch = never> = A1 extends A2 ? A1 : Catch;
+
+/**
+ * @private
+ */
+export type Narrow<A> = Try<A, [], NarrowRaw<A>>;
+
+export interface AnyDeepKeyAndValue<K extends string = string, V extends any = any> {
+  key: K;
+  value: V;
+}
+
+export type ArrayAccessor<TParent extends AnyDeepKeyAndValue> =
+  `${TParent['key'] extends never ? '' : TParent['key']}.${number}`;
+
+export interface ArrayDeepKeyAndValue<
+  in out TParent extends AnyDeepKeyAndValue,
+  in out T extends ReadonlyArray<any>,
+> extends AnyDeepKeyAndValue {
+  key: ArrayAccessor<TParent>;
+  value: T[number] | Nullable<TParent['value']>;
+}
+
+export type DeepKeyAndValueArray<
+  TParent extends AnyDeepKeyAndValue,
+  T extends ReadonlyArray<any>,
+  TAcc,
+> = DeepKeysAndValuesImpl<
+  NonNullable<T[number]>,
+  ArrayDeepKeyAndValue<TParent, T>,
+  TAcc | ArrayDeepKeyAndValue<TParent, T>
+>;
+
+export type TupleAccessor<
+  TParent extends AnyDeepKeyAndValue,
+  TKey extends string,
+> = `${TParent['key'] extends never ? '' : TParent['key']}[${TKey}]`;
+
+export interface TupleDeepKeyAndValue<
+  in out TParent extends AnyDeepKeyAndValue,
+  in out T,
+  in out TKey extends AllTupleKeys<T>,
+> extends AnyDeepKeyAndValue {
+  key: TupleAccessor<TParent, TKey>;
+  value: T[TKey] | Nullable<TParent['value']>;
+}
+
+export type AllTupleKeys<T> = T extends any ? keyof T & `${number}` : never;
+
+export type DeepKeyAndValueTuple<
+  TParent extends AnyDeepKeyAndValue,
+  T extends ReadonlyArray<any>,
+  TAcc,
+  TAllKeys extends AllTupleKeys<T> = AllTupleKeys<T>,
+> = TAllKeys extends any
+  ? DeepKeysAndValuesImpl<
+      NonNullable<T[TAllKeys]>,
+      TupleDeepKeyAndValue<TParent, T, TAllKeys>,
+      TAcc | TupleDeepKeyAndValue<TParent, T, TAllKeys>
+    >
+  : never;
+
+export type AllObjectKeys<T> = T extends any ? keyof T & (string | number) : never;
+
+export type ObjectAccessor<
+  TParent extends AnyDeepKeyAndValue,
+  TKey extends string | number,
+> = TParent['key'] extends never ? `${TKey}` : `${TParent['key']}.${TKey}`;
+
+export type Nullable<T> = T & (undefined | null);
+
+export type ObjectValue<TParent extends AnyDeepKeyAndValue, T, TKey extends AllObjectKeys<T>> =
+  | T[TKey]
+  | Nullable<TParent['value']>;
+
+export interface ObjectDeepKeyAndValue<
+  in out TParent extends AnyDeepKeyAndValue,
+  in out T,
+  in out TKey extends AllObjectKeys<T>,
+> extends AnyDeepKeyAndValue {
+  key: ObjectAccessor<TParent, TKey>;
+  value: ObjectValue<TParent, T, TKey>;
+}
+
+export type DeepKeyAndValueObject<
+  TParent extends AnyDeepKeyAndValue,
+  T,
+  TAcc,
+  TAllKeys extends AllObjectKeys<T> = AllObjectKeys<T>,
+> = TAllKeys extends any
+  ? DeepKeysAndValuesImpl<
+      NonNullable<T[TAllKeys]>,
+      ObjectDeepKeyAndValue<TParent, T, TAllKeys>,
+      TAcc | ObjectDeepKeyAndValue<TParent, T, TAllKeys>
+    >
+  : never;
+
+export type UnknownAccessor<TParent extends AnyDeepKeyAndValue> = TParent['key'] extends never
+  ? string
+  : `${TParent['key']}.${string}`;
+
+export interface UnknownDeepKeyAndValue<TParent extends AnyDeepKeyAndValue> extends AnyDeepKeyAndValue {
+  key: UnknownAccessor<TParent>;
+  value: unknown;
+}
+
+export type DeepKeysAndValues<T> =
+  DeepKeysAndValuesImpl<T> extends AnyDeepKeyAndValue ? DeepKeysAndValuesImpl<T> : never;
+
+export type DeepKeysAndValuesImpl<T, TParent extends AnyDeepKeyAndValue = never, TAcc = never> = unknown extends T
+  ? TAcc | UnknownDeepKeyAndValue<TParent>
+  : unknown extends T // this stops runaway recursion when T is any
+    ? T
+    : T extends string | number | boolean | bigint | Date
+      ? TAcc
+      : T extends ReadonlyArray<any>
+        ? number extends T['length']
+          ? DeepKeyAndValueArray<TParent, T, TAcc>
+          : DeepKeyAndValueTuple<TParent, T, TAcc>
+        : keyof T extends never
+          ? TAcc | UnknownDeepKeyAndValue<TParent>
+          : T extends object
+            ? DeepKeyAndValueObject<TParent, T, TAcc>
+            : TAcc;
+
+export type DeepRecord<T> = {
+  [TRecord in DeepKeysAndValues<T> as TRecord['key']]: TRecord['value'];
+};
+
+/**
+ * The keys of an object or array, deeply nested.
+ */
+export type DeepKeys<T> = unknown extends T ? string : DeepKeysAndValues<T>['key'];
+
+/**
+ * Infer the type of a deeply nested property within an object or an array.
+ */
+export type DeepValue<TValue, TAccessor> = unknown extends TValue
+  ? TValue
+  : TAccessor extends DeepKeys<TValue>
+    ? DeepRecord<TValue>[TAccessor]
+    : never;
+
+/**
+ * The keys of an object or array, deeply nested and only with a value of TValue
+ */
+export type DeepKeysOfType<TData, TValue> = Extract<
+  DeepKeysAndValues<TData>,
+  AnyDeepKeyAndValue<string, TValue>
+>['key'];
+
+/**
+ * Maps the deep keys of TFormData to the shallow keys of TFieldGroupData.
+ *  Since using template strings as keys is impractical, it relies on shallow keys only.
+ */
+export type FieldsMap<TFormData, TFieldGroupData> = TFieldGroupData extends any[]
+  ? never
+  : string extends keyof TFieldGroupData
+    ? never
+    : {
+        [K in keyof TFieldGroupData]: DeepKeysOfType<TFormData, TFieldGroupData[K]>;
+      };