oxform-core 0.1.0

package/export/index.ts

@@ -0,0 +1,7 @@
+export { FieldApi } from '#field-api';
+export { FormApi } from '#form-api';
+
+export type * from '#field-api';
+export type * from '#form-api.types';
+export type * from '#more-types';
+export type { EventLike } from '#types';

package/export/schema.ts

@@ -0,0 +1 @@
+export type { StandardSchema } from '#types';

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "oxform-core",
+  "version": "0.1.0",
+  "description": "Oxform is a lean and flexible framework-agnostic form library.",
+  "author": "Frantss <frantss.bongiovanni@gmail.com>",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "imports": {
+    "#*": [
+      "./src/*.ts",
+      "./src/**/*.ts"
+    ]
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json",
+    "./schema": "./dist/schema.js"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsdown --config-loader unrun",
+    "test": "vitest",
+    "lint:types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "catalog:oxform",
+    "@tanstack/store": "^0.8.0",
+    "remeda": "^2.32.0",
+    "type-fest": "^5.3.1"
+  },
+  "devDependencies": {
+    "tsdown": "catalog:oxform",
+    "typescript": "catalog:oxform",
+    "vitest": "catalog:oxform",
+    "zod": "^4.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,13 @@
+# Oxform Core
+
+This package contains the core logic for Oxform.
+You probably don't want to use this package directly. Instead check out the React integration (`oxform-react`).
+
+## Installation
+
+```bash
+npm install oxform-core
+yarn add oxform-core
+pnpm add oxform-core
+bun add oxform-core
+```

package/src/field-api.constants.ts

@@ -0,0 +1,15 @@
+import type { PersistedFieldMeta, PersistedFormStatus } from '#form-api.types';
+
+export const defaultMeta = {
+  blurred: false,
+  touched: false,
+  dirty: false,
+} satisfies PersistedFieldMeta;
+
+export const defaultStatus = {
+  submits: 0,
+  submitting: false,
+  validating: false,
+  successful: false,
+  dirty: false,
+} satisfies PersistedFormStatus;

package/src/field-api.ts

@@ -0,0 +1,139 @@
+import type { FormApi } from '#form-api';
+import type {
+  FieldChangeOptions,
+  FieldMeta,
+  FormIssue,
+  FormResetFieldOptions,
+  FormSetErrorsOptions,
+  ValidateOptions,
+} from '#form-api.types';
+import type { DeepKeys, DeepValue } from '#more-types';
+import type { EventLike, StandardSchema } from '#types';
+import { get } from '#utils/get';
+import type { Updater } from '#utils/update';
+import { Derived } from '@tanstack/store';
+import { stringToPath } from 'remeda';
+
+export type FieldOptions<
+  Schema extends StandardSchema,
+  Name extends DeepKeys<StandardSchema.InferInput<Schema>> = DeepKeys<StandardSchema.InferInput<Schema>>,
+> = {
+  form: FormApi<Schema>;
+  name: Name;
+};
+
+export type FieldStore<Value> = {
+  value: Value;
+  defaultValue: Value;
+  meta: FieldMeta;
+  errors: FormIssue[];
+};
+
+export type FieldProps<Value> = {
+  defaultValue: Value;
+  value: Value;
+  ref: (element: HTMLElement | null) => void;
+  onChange: (event: EventLike) => void;
+  onBlur: (event: EventLike) => void;
+  onFocus: (event: EventLike) => void;
+};
+
+export class FieldApi<
+  Schema extends StandardSchema,
+  Name extends DeepKeys<StandardSchema.InferInput<Schema>>,
+  in out Value extends DeepValue<StandardSchema.InferInput<Schema>, Name>,
+> {
+  public options: FieldOptions<Schema, Name>;
+  public form: FormApi<Schema>;
+  public store: Derived<FieldStore<Value>>;
+
+  constructor(options: FieldOptions<Schema, Name>) {
+    this.options = options;
+    this.form = options.form;
+
+    this.store = new Derived<FieldStore<Value>>({
+      deps: [this.form.store],
+      fn: () => {
+        const value = this.form.field.get(this.options.name as never) as Value;
+        const defaultValue = get(this.form.options.defaultValues as never, stringToPath(this.options.name)) as Value;
+        const meta = this.form.field.meta(this.options.name as never);
+        const errors = this.form.field.errors(this.options.name as never);
+
+        return {
+          value,
+          defaultValue,
+          meta,
+          errors,
+        };
+      },
+    });
+  }
+
+  public '~mount' = () => {
+    const unsubscribe = this.store.mount();
+
+    return unsubscribe;
+  };
+
+  public '~update' = (options: FieldOptions<Schema, Name>) => {
+    // ref: https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1300
+    this.options = options;
+  };
+
+  public get value() {
+    return this.store.state.value;
+  }
+
+  public get defaultValue() {
+    return this.store.state.defaultValue;
+  }
+
+  public get meta() {
+    return this.store.state.meta;
+  }
+
+  public get errors() {
+    return this.store.state.errors;
+  }
+
+  public focus = () => this.form.field.focus(this.options.name);
+
+  public blur = () => this.form.field.blur(this.options.name);
+
+  /**
+   * Changes the value of this field with optional control over side effects.
+   * @param value - The new value to set for the field
+   * @param options - Optional configuration for controlling validation, dirty state, and touched state
+   */
+  public change = (value: Updater<Value>, options?: FieldChangeOptions) => {
+    return this.form.field.change(this.options.name, value as never, options);
+  };
+
+  public register = () => this.form.field.register(this.options.name);
+
+  /**
+   * Validates this specific field using the specified validation type.
+   * @param options - Optional validation options specifying the validation type ('change' | 'submit' | 'blur' | 'focus')
+   * @returns Promise resolving to an array of validation issues for this field
+   */
+  public validate = (options?: ValidateOptions) => {
+    return this.form.validate(this.options.name, options);
+  };
+
+  /**
+   * Resets this field to its default value and optionally resets metadata and errors.
+   * @param options - Reset options for controlling what gets reset and what gets kept
+   */
+  public reset = (options?: FormResetFieldOptions<Value>) => {
+    return this.form.field.reset(this.options.name, options);
+  };
+
+  /**
+   * Sets validation errors for this specific field.
+   * @param errors - Array of validation errors to set
+   * @param mode - How to handle existing errors: 'replace' (default), 'append', or 'keep'
+   */
+  public setErrors = (errors: FormIssue[], options?: FormSetErrorsOptions) => {
+    return this.form.field.setErrors(this.options.name, errors, options);
+  };
+}

package/src/form-api.ts

@@ -0,0 +1,84 @@
+import { defaultStatus } from '#field-api.constants';
+import type { FormOptions, FormResetOptions, FormSubmitErrorHandler, FormSubmitSuccessHandler } from '#form-api.types';
+import { FormArrayFieldApi } from '#form-array-field-api';
+import { FormContextApi } from '#form-context-api';
+import { FormFieldApi } from '#form-field-api';
+import type { StandardSchema } from '#types';
+
+export class FormApi<Schema extends StandardSchema> {
+  private context: FormContextApi<Schema>;
+  public field: FormFieldApi<Schema>;
+  public array: FormArrayFieldApi<Schema>;
+
+  constructor(options: FormOptions<Schema>) {
+    this.context = new FormContextApi(options);
+    this.field = new FormFieldApi(this.context);
+    this.array = new FormArrayFieldApi({ field: this.field, context: this.context });
+  }
+
+  public '~mount' = () => {
+    const unsubscribe = this.context.store.mount();
+
+    return unsubscribe;
+  };
+
+  public '~update' = (options: FormOptions<NoInfer<Schema>>) => {
+    this.context.options = options;
+  };
+
+  public get store() {
+    return this.context.store;
+  }
+
+  public get status() {
+    return this.context.store.state.status;
+  }
+
+  public get values() {
+    return this.context.store.state.values;
+  }
+
+  public get options() {
+    return this.context.options;
+  }
+
+  public get validate() {
+    return this.context.validate;
+  }
+
+  public submit =
+    (onSuccess: FormSubmitSuccessHandler<NoInfer<Schema>>, onError?: FormSubmitErrorHandler<NoInfer<Schema>>) =>
+    async () => {
+      this.context.setStatus({ submitting: true, dirty: true });
+
+      const issues = await this.context.validate(undefined, { type: 'submit' });
+      const valid = issues.length === 0;
+
+      if (valid) {
+        await onSuccess(this.context.store.state.values as never, this as never);
+      } else {
+        await onError?.(issues, this as never);
+      }
+
+      this.context.setStatus({
+        submits: this.context.persisted.state.status.submits + 1,
+        submitting: false,
+        successful: valid,
+      });
+    };
+
+  public reset = (options?: FormResetOptions<StandardSchema.InferInput<NoInfer<Schema>>>) => {
+    this.context.persisted.setState(current => {
+      return {
+        values: options?.values ?? this.context.options.defaultValues,
+        fields: options?.keep?.fields ? current.fields : {},
+        refs: options?.keep?.refs ? current.refs : {},
+        errors: options?.keep?.errors ? current.errors : {},
+        status: {
+          ...defaultStatus,
+          ...options?.status,
+        },
+      };
+    });
+  };
+}

package/src/form-api.types.ts

@@ -0,0 +1,148 @@
+import type { FormApi } from '#form-api';
+import type { DeepKeys } from '#more-types';
+import type { PartialDeep, Simplify, StandardSchema } from '#types';
+
+export type PersistedFormStatus = {
+  submits: number;
+  submitting: boolean;
+  validating: boolean;
+  successful: boolean;
+  dirty: boolean;
+};
+
+export type FormStatus = Simplify<
+  PersistedFormStatus & {
+    submitted: boolean;
+    valid: boolean;
+  }
+>;
+
+export type PersistedFieldMeta = {
+  blurred: boolean;
+  touched: boolean;
+  dirty: boolean;
+};
+
+export type FieldMeta = Simplify<
+  PersistedFieldMeta & {
+    touched: boolean;
+    default: boolean;
+    valid: boolean;
+    pristine: boolean;
+  }
+>;
+
+export type FormBaseStore<Schema extends StandardSchema> = {
+  values: StandardSchema.InferInput<Schema>;
+  fields: Record<string, PersistedFieldMeta>;
+  refs: Record<string, HTMLElement | null>;
+  status: PersistedFormStatus;
+  errors: Record<string, FormIssue[]>;
+};
+
+export type FormStore<Schema extends StandardSchema> = {
+  values: StandardSchema.InferInput<Schema>;
+  fields: Record<string, FieldMeta>;
+  refs: Record<string, HTMLElement | null>;
+  status: FormStatus;
+  errors: Record<string, FormIssue[]>;
+};
+
+export type FieldControl<Value> = {
+  focus: () => void;
+  blur: () => void;
+  change: (value: Value) => void;
+  register: (element: HTMLElement | null) => void;
+};
+
+type FormValidatorSchema<Schema extends StandardSchema> = NoInfer<
+  StandardSchema<PartialDeep<StandardSchema.InferInput<Schema>>>
+>;
+type FormValidatorFunction<Schema extends StandardSchema> = (store: FormStore<Schema>) => FormValidatorSchema<Schema>;
+type FormValidator<Schema extends StandardSchema> = FormValidatorSchema<Schema> | FormValidatorFunction<Schema>;
+
+export type FormOptions<Schema extends StandardSchema> = {
+  schema: Schema;
+  values?: StandardSchema.InferInput<Schema>;
+  defaultValues: StandardSchema.InferInput<Schema>;
+  validate?: {
+    change?: FormValidator<Schema>;
+    submit?: FormValidator<Schema>;
+    blur?: FormValidator<Schema>;
+    focus?: FormValidator<Schema>;
+  };
+  related?: Record<DeepKeys<StandardSchema.InferInput<Schema>>, DeepKeys<StandardSchema.InferInput<Schema>>[]>;
+};
+
+export type FormIssue = StandardSchema.Issue;
+
+export type ValidationType = 'change' | 'submit' | 'blur' | 'focus';
+
+export type ValidateOptions = {
+  type?: ValidationType;
+};
+
+export type FieldChangeOptions = {
+  should?: {
+    /** Whether to validate the field after changing its value. Defaults to true. */
+    validate?: boolean;
+    /** Whether to mark the field as dirty after changing its value. Defaults to true. */
+    dirty?: boolean;
+    /** Whether to mark the field as touched after changing its value. Defaults to true. */
+    touch?: boolean;
+  };
+};
+
+export type FieldResetMeta = {
+  blurred?: boolean;
+  touched?: boolean;
+  dirty?: boolean;
+};
+
+export type FieldResetKeepOptions = {
+  errors?: boolean;
+  refs?: boolean;
+  meta?: boolean;
+};
+
+export type FormResetFieldOptions<Value> = {
+  value?: Value;
+  meta?: FieldResetMeta;
+  keep?: FieldResetKeepOptions;
+};
+
+export type FormResetKeepOptions = {
+  /** Keep current field errors */
+  errors?: boolean;
+  /** Keep current references to html input elements */
+  refs?: boolean;
+  /** Keep current field metadata */
+  fields?: boolean;
+};
+
+export type FormResetOptions<Values> = {
+  values?: Values;
+  status?: Partial<PersistedFormStatus>;
+  keep?: FormResetKeepOptions;
+};
+
+export type FieldSetErrorsMode = 'replace' | 'append' | 'keep';
+
+export type FormSetErrorsOptions = {
+  mode?: FieldSetErrorsMode;
+};
+
+export type FormSubmitSuccessHandler<Schema extends StandardSchema> = (
+  data: StandardSchema.InferOutput<Schema>,
+  form: FormApi<Schema>,
+) => void | Promise<void>;
+
+export type FormSubmitErrorHandler<Schema extends StandardSchema> = (
+  issues: FormIssue[],
+  form: FormApi<Schema>,
+) => void | Promise<void>;
+
+export type FormSubmitHandlers<Schema extends StandardSchema> = {
+  onSuccess: FormSubmitSuccessHandler<Schema>;
+  onError?: FormSubmitErrorHandler<Schema>;
+};

package/src/form-array-field-api.ts

@@ -0,0 +1,233 @@
+import { defaultMeta } from '#field-api.constants';
+import type { FieldChangeOptions } from '#form-api.types';
+import type { FormContextApi } from '#form-context-api';
+import type { FormFieldApi } from '#form-field-api';
+import type { DeepKeysOfType, DeepValue, UnwrapOneLevelOfArray } from '#more-types';
+import type { StandardSchema } from '#types';
+import { get } from '#utils/get';
+import { update, type Updater } from '#utils/update';
+import { stringToPath } from 'remeda';
+
+export class FormArrayFieldApi<
+  Schema extends StandardSchema<any>,
+  Values extends StandardSchema.InferInput<Schema> = StandardSchema.InferInput<Schema>,
+  ArrayField extends DeepKeysOfType<Values, any[] | null | undefined> = DeepKeysOfType<
+    Values,
+    any[] | null | undefined
+  >,
+> {
+  private context: FormContextApi<Schema>;
+  private field: FormFieldApi<Schema>;
+
+  constructor({ field, context }: { field: FormFieldApi<Schema>; context: FormContextApi<Schema> }) {
+    this.context = context;
+    this.field = field;
+  }
+
+  public insert = <Name extends ArrayField>(
+    name: Name,
+    index: number,
+    value: Updater<UnwrapOneLevelOfArray<DeepValue<Values, Name>>>,
+    options?: FieldChangeOptions,
+  ) => {
+    if (index < 0) index = 0;
+
+    this.field.change(
+      name,
+      current => {
+        const array = (current as any[]) ?? [];
+
+        return [
+          ...array.slice(0, index),
+          ...(Array.from({ length: index - array.length }, () => undefined) as any[]),
+          update(value, current as never),
+          ...array.slice(index),
+        ] as never;
+      },
+      options,
+    );
+
+    this.context.persisted.setState(current => {
+      const fields = { ...current.fields };
+      const value = get(current.values as never, stringToPath(name)) as any[] | undefined;
+      const length = value?.length;
+
+      if (length === undefined) return current;
+
+      for (let i = index; i < length; i++) {
+        const moving = current.fields[`${name}.${i}`];
+        fields[`${name}.${i + 1}`] = moving ?? defaultMeta;
+      }
+
+      fields[`${name}.${index}`] = defaultMeta;
+
+      return {
+        ...current,
+        fields,
+      };
+    });
+  };
+
+  public append = <Name extends ArrayField>(
+    name: Name,
+    value: UnwrapOneLevelOfArray<DeepValue<Values, Name>>,
+    options?: FieldChangeOptions,
+  ) => {
+    const current = this.field.get(name) as any[];
+    return this.insert(name, current?.length ?? 0, value, options);
+  };
+
+  public prepend = <Name extends ArrayField>(
+    name: Name,
+    value: UnwrapOneLevelOfArray<DeepValue<Values, Name>>,
+    options?: FieldChangeOptions,
+  ) => {
+    return this.insert(name, 0, value, options);
+  };
+
+  public swap = <Name extends ArrayField>(name: Name, from: number, to: number, options?: FieldChangeOptions) => {
+    const start = from >= 0 ? from : 0;
+    const end = to >= 0 ? to : 0;
+
+    this.field.change(
+      name,
+      current => {
+        const array = (current as any[]) ?? [];
+
+        if (start === end) return array as never; // no-op
+
+        const a = array[start];
+        const b = array[end];
+
+        return [...array.slice(0, start), b, ...array.slice(start + 1, end), a, ...array.slice(end + 1)] as never;
+      },
+      options,
+    );
+
+    this.context.persisted.setState(current => {
+      const fields = { ...current.fields };
+
+      fields[`${name}.${start}`] = current.fields[`${name}.${end}`] ?? defaultMeta;
+      fields[`${name}.${end}`] = current.fields[`${name}.${start}`] ?? defaultMeta;
+
+      return {
+        ...current,
+        fields,
+      };
+    });
+  };
+
+  public move<Name extends ArrayField>(name: Name, _from: number, _to: number, options?: FieldChangeOptions) {
+    const from = Math.max(_from, 0);
+    const to = Math.max(_to, 0);
+    const backwards = from > to;
+
+    this.field.change(
+      name,
+      current => {
+        const array: any[] = current ? [...(current as any[])] : [];
+
+        if (from === to) return array as never;
+
+        const moved = array[from];
+        return array.toSpliced(backwards ? to : to + 1, 0, moved).toSpliced(backwards ? from + 1 : from, 1) as never;
+      },
+      options,
+    );
+
+    this.context.persisted.setState(current => {
+      const fields = { ...current.fields };
+      const value = get(current.values as never, stringToPath(name)) as any[] | undefined;
+      const length = value?.length;
+
+      const start = Math.min(from, to);
+      const end = Math.max(from, to);
+
+      if (length === undefined) return current;
+
+      if (!backwards) {
+        fields[`${name}.${to}`] = current.fields[`${name}.${from}`] ?? defaultMeta;
+      }
+
+      for (let i = backwards ? start + 1 : start; i < end; i++) {
+        const shift = backwards ? -1 : 1;
+        const moving = current.fields[`${name}.${i + shift}`];
+        fields[`${name}.${i}`] = moving ?? defaultMeta;
+      }
+
+      return {
+        ...current,
+        fields,
+      };
+    });
+  }
+
+  public update = <Name extends ArrayField>(
+    name: Name,
+    index: number,
+    value: Updater<UnwrapOneLevelOfArray<DeepValue<Values, Name>>>,
+    options?: FieldChangeOptions,
+  ) => {
+    this.field.change(
+      name,
+      current => {
+        const array = (current as any[]) ?? [];
+        const position = Math.max(Math.min(index, array.length - 1), 0);
+
+        return [...array.slice(0, position), update(value, current as never), ...array.slice(position + 1)] as never;
+      },
+      options,
+    );
+
+    this.context.resetFieldMeta(`${name}.${index}`);
+    this.context.setFieldMeta(`${name}.${index}`, {
+      dirty: options?.should?.dirty !== false,
+      touched: options?.should?.touch !== false,
+    });
+  };
+
+  public remove<Name extends ArrayField>(name: Name, index: number, options?: FieldChangeOptions) {
+    let position = index;
+
+    this.field.change(
+      name,
+      current => {
+        const array = (current as any[]) ?? [];
+        position = Math.max(Math.min(index, array.length - 1), 0);
+
+        return [...array.slice(0, position), ...array.slice(position + 1)] as never;
+      },
+      { ...options, should: { ...options?.should, validate: false } },
+    );
+
+    this.context.persisted.setState(current => {
+      const fields = { ...current.fields };
+      const value = get(current.values as never, stringToPath(name)) as any[] | undefined;
+      const length = value?.length ?? 0;
+
+      for (let i = position; i < length; i++) {
+        const moving = current.fields[`${name}.${i + 1}`];
+        fields[`${name}.${i}`] = moving ?? defaultMeta;
+      }
+
+      delete fields[`${name}.${length}`];
+
+      return {
+        ...current,
+        fields,
+      };
+    });
+
+    const shouldValidate = options?.should?.validate !== false;
+    if (shouldValidate) void this.context.validate(name, { type: 'change' });
+  }
+
+  public replace<Name extends ArrayField>(
+    name: Name,
+    value: Updater<DeepValue<Values, Name>>,
+    options?: FieldChangeOptions,
+  ) {
+    this.context.resetFieldMeta(name);
+    this.field.change(name, value as never, options);
+  }
+}