@rebasepro/forms 0.0.1-canary.4829d6e

package/src/Field.tsx

@@ -0,0 +1,164 @@
+import * as React from "react";
+import { useFormex } from "./Formex";
+import { getIn, isFunction, isObject } from "./utils";
+import { FormexController } from "./types";
+
+export interface FieldInputProps<Value> {
+    /** Value of the field */
+    value: Value;
+    /** Name of the field */
+    name: string;
+    /** Multiple select? */
+    multiple?: boolean;
+    /** Is the field checked? */
+    checked?: boolean;
+    /** Change event handler */
+    onChange: (event: React.SyntheticEvent) => void,
+    /** Blur event handler */
+    onBlur: (event: React.FocusEvent) => void,
+}
+
+export interface FormexFieldProps<Value = any, FormValues extends object = object> {
+    field: FieldInputProps<Value>;
+    form: FormexController<FormValues>;
+}
+
+export interface FieldConfig<Value, C extends React.ElementType | undefined = undefined> {
+
+    /**
+     * Component to render. Can either be a string e.g. 'select', 'input', or 'textarea', or a component.
+     */
+    as?:
+        | C
+        | string
+        | React.ForwardRefExoticComponent<Record<string, unknown>>;
+
+    /**
+     * Children render function <Field name>{props => ...}</Field>)
+     */
+    children?: ((props: FormexFieldProps<Value>) => React.ReactNode) | React.ReactNode;
+
+    /**
+     * Validate a single field value independently
+     */
+    // validate?: FieldValidator;
+
+    /**
+     * Used for 'select' and related input types.
+     */
+    multiple?: boolean;
+
+    /**
+     * Field name
+     */
+    name: string;
+
+    /** HTML input type */
+    type?: string;
+
+    /** Field value */
+    value?: unknown;
+
+    /** Inner ref */
+    innerRef?: (instance: unknown) => void;
+
+}
+
+export type FieldProps<T, C extends React.ElementType | undefined> = {
+    as?: C;
+} & (C extends React.ElementType ? (React.ComponentProps<C> & FieldConfig<T, C>) : FieldConfig<T, C>);
+
+export function Field<T, C extends React.ElementType | undefined = undefined>({
+                                                                                  validate,
+                                                                                  name,
+                                                                                  children,
+                                                                                  as: is, // `as` is reserved in typescript lol
+                                                                                  // component,
+                                                                                  className,
+                                                                                  ...props
+                                                                              }: FieldProps<T, C>) {
+    const formex = useFormex();
+
+    const field = getFieldProps({ name,
+...props }, formex);
+
+    if (isFunction(children)) {
+        return children({ field,
+form: formex });
+    }
+
+    // if (component) {
+    //     if (typeof component === "string") {
+    //         const { innerRef, ...rest } = props;
+    //         return React.createElement(
+    //             component,
+    //             { ref: innerRef, ...field, ...rest, className },
+    //             children
+    //         );
+    //     }
+    //     return React.createElement(
+    //         component,
+    //         { field, form: formex, ...props, className },
+    //         children
+    //     );
+    // }
+
+    // default to input here so we can check for both `as` and `children` above
+    const asElement = is || "input";
+
+    if (typeof asElement === "string") {
+        const { innerRef, ...rest } = props;
+        return React.createElement(
+            asElement,
+            { ref: innerRef,
+...field,
+...rest,
+className },
+            children
+        );
+    }
+
+    return React.createElement(asElement, { ...field,
+...props,
+className }, children);
+}
+
+const getFieldProps = (nameOrOptions: string | FieldConfig<unknown>, formex: FormexController<object>): FieldInputProps<unknown> => {
+    const name: string = typeof nameOrOptions === "string"
+        ? nameOrOptions
+        : nameOrOptions.name;
+    const valueState = getIn(formex.values as Record<string, unknown>, name);
+
+    const field: FieldInputProps<unknown> = {
+        name: name as string,
+        value: valueState,
+        onChange: formex.handleChange,
+        onBlur: formex.handleBlur
+    };
+    if (typeof nameOrOptions !== "string") {
+        const {
+            type,
+            value: valueProp, // value is special for checkboxes
+            as: is,
+            multiple
+        } = nameOrOptions as FieldConfig<unknown>;
+
+        if (type === "checkbox") {
+            if (valueProp === undefined) {
+                field.checked = !!valueState;
+            } else {
+                field.checked = !!(
+                    Array.isArray(valueState) && ~valueState.indexOf(valueProp)
+                );
+                field.value = valueProp;
+            }
+        } else if (type === "radio") {
+            field.checked = valueState === valueProp;
+            field.value = valueProp;
+        } else if (is === "select" && multiple) {
+            field.value = field.value || [];
+            field.multiple = true;
+        }
+    }
+    return field;
+};

package/src/Formex.tsx

@@ -0,0 +1,15 @@
+import React, { useContext } from "react";
+import { FormexController } from "./types";
+
+
+const FormexContext = React.createContext<FormexController<any> | null>(null);
+
+export const useFormex = <T = any>() => {
+    const ctx = useContext(FormexContext);
+    if (!ctx) throw new Error("useFormex must be used within a Formex provider");
+    return ctx as FormexController<T>;
+};
+
+export const Formex = <T = any>({ value, children }: { value: FormexController<T>, children: React.ReactNode }) => {
+    return <FormexContext.Provider value={value}>{children}</FormexContext.Provider>;
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./Field";
+export * from "./Formex";
+export * from "./types";
+export * from "./utils";
+export * from "./useCreateFormex";

package/src/types.ts

@@ -0,0 +1,45 @@
+import React, { FormEvent } from "react";
+
+export type FormexController<T = any> = {
+    values: T;
+    initialValues: T;
+    setValues: (values: T) => void;
+    setFieldValue: (key: string, value: unknown, shouldValidate?: boolean) => void;
+    touched: Record<string, boolean>;
+    setFieldTouched: (key: string, touched: boolean, shouldValidate?: boolean) => void;
+    setTouched: (touched: Record<string, boolean>) => void;
+    dirty: boolean;
+    setDirty: (dirty: boolean) => void;
+    setSubmitCount: (submitCount: number) => void;
+    errors: Record<string, string>;
+    setFieldError: (key: string, error?: string) => void;
+    handleChange: (event: React.SyntheticEvent) => void,
+    handleBlur: (event: React.FocusEvent) => void,
+    handleSubmit: (event?: FormEvent<HTMLFormElement>) => void;
+    validate: () => void;
+    resetForm: (props?: FormexResetProps<T>) => void;
+    submitCount: number;
+    isSubmitting: boolean;
+    setSubmitting: (isSubmitting: boolean) => void;
+    isValidating: boolean;
+    /**
+     * The version of the form. This is incremented every time the form is reset
+     * or the form is submitted.
+     */
+    version: number;
+
+    debugId?: string;
+
+    undo: () => void;
+    redo: () => void;
+
+    canUndo: boolean;
+    canRedo: boolean;
+}
+
+export type FormexResetProps<T = any> = {
+    values?: T;
+    submitCount?: number;
+    errors?: Record<string, string>;
+    touched?: Record<string, boolean>;
+};

package/src/useCreateFormex.tsx

@@ -0,0 +1,297 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { getIn, setIn } from "./utils";
+import { deepEqual as equal } from "fast-equals";
+
+import { FormexController, FormexResetProps } from "./types";
+
+export function useCreateFormex<T = any>({
+    initialValues,
+    initialErrors,
+    initialDirty,
+    initialTouched,
+    validation,
+    validateOnChange = false,
+    validateOnInitialRender = false,
+    onSubmit,
+    onReset,
+    onValuesChangeDeferred,
+    debugId
+}: {
+    initialValues: T;
+    initialErrors?: Record<string, string>;
+    initialDirty?: boolean;
+    initialTouched?: Record<string, boolean>;
+    validateOnChange?: boolean;
+    validateOnInitialRender?: boolean;
+    validation?: (
+        values: T
+    ) =>
+        | Record<string, string>
+        | Promise<Record<string, string>>
+        | undefined
+        | void;
+    onValuesChangeDeferred?: (values: T, controller: FormexController<T>) => void;
+    onSubmit?: (values: T, controller: FormexController<T>) => void | Promise<void>;
+    onReset?: (controller: FormexController<T>) => void | Promise<void>;
+    debugId?: string;
+}): FormexController<T> {
+    const initialValuesRef = useRef<T>(initialValues);
+    const valuesRef = useRef<T>(initialValues);
+    const debugIdRef = useRef<string | undefined>(debugId);
+
+    const [values, setValuesInner] = useState<T>(initialValues);
+    const [touchedState, setTouchedState] = useState<Record<string, boolean>>(initialTouched ?? {});
+    const [errors, setErrors] = useState<Record<string, string>>(initialErrors ?? {});
+    const [dirty, setDirty] = useState(initialDirty ?? false);
+    const [submitCount, setSubmitCount] = useState(0);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [isValidating, setIsValidating] = useState(false);
+    const [version, setVersion] = useState(0);
+
+    const onValuesChangeRef = useRef(onValuesChangeDeferred);
+    onValuesChangeRef.current = onValuesChangeDeferred;
+    const debounceTimeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+    const callDebouncedOnValuesChange = useCallback((values: T) => {
+        if (onValuesChangeRef.current) {
+            if (debounceTimeoutRef.current) {
+                clearTimeout(debounceTimeoutRef.current);
+            }
+            debounceTimeoutRef.current = setTimeout(() => {
+                onValuesChangeRef.current?.(values, controllerRef.current);
+            }, 300);
+        }
+    }, []);
+
+    // Replace state for history with refs
+    const historyRef = useRef<T[]>([initialValues]);
+    const historyIndexRef = useRef<number>(0);
+
+    useEffect(() => {
+        if (validateOnInitialRender) {
+            validate();
+        }
+    }, []);
+
+    const setValues = useCallback((newValues: T) => {
+        valuesRef.current = newValues;
+        setValuesInner(newValues);
+        setDirty(!equal(initialValuesRef.current, newValues));
+        // Update history using refs
+        const newHistory = historyRef.current.slice(0, historyIndexRef.current + 1);
+        newHistory.push(newValues);
+        historyRef.current = newHistory;
+        historyIndexRef.current = newHistory.length - 1;
+        callDebouncedOnValuesChange(newValues);
+    }, [callDebouncedOnValuesChange]);
+
+    const validate = useCallback(async () => {
+        setIsValidating(true);
+        const validationErrors = await validation?.(valuesRef.current);
+        setErrors(validationErrors ?? {});
+        setIsValidating(false);
+        return validationErrors;
+    }, [validation]);
+
+    const setFieldValue = useCallback(
+        (key: string, value: unknown, shouldValidate?: boolean) => {
+            const newValues = setIn(valuesRef.current as Record<string, unknown>, key, value) as T;
+            valuesRef.current = newValues;
+            setValuesInner(newValues);
+            if (!equal(getIn(initialValuesRef.current as Record<string, unknown>, key), value)) {
+                setDirty(true);
+            }
+            if (shouldValidate) {
+                validate();
+            }
+            // Update history using refs
+            const newHistory = historyRef.current.slice(0, historyIndexRef.current + 1);
+            newHistory.push(newValues);
+            historyRef.current = newHistory;
+            historyIndexRef.current = newHistory.length - 1;
+            callDebouncedOnValuesChange(newValues);
+        },
+        [validate, callDebouncedOnValuesChange]
+    );
+
+    const setFieldError = useCallback((key: string, error: string | undefined) => {
+        setErrors((prevErrors: Record<string, string>) => {
+            const newErrors = { ...prevErrors };
+            if (error) {
+                newErrors[key] = error;
+            } else {
+                delete newErrors[key];
+            }
+            return newErrors;
+        });
+    }, []);
+
+    const setFieldTouched = useCallback(
+        (key: string, touched: boolean, shouldValidate?: boolean) => {
+            setTouchedState((prev: Record<string, boolean>) => ({
+                ...prev,
+                [key]: touched
+            }));
+            if (shouldValidate) {
+                validate();
+            }
+        },
+        [validate]
+    );
+
+    const handleChange = useCallback(
+        (event: React.SyntheticEvent) => {
+            const target = event.target as HTMLInputElement;
+            let value;
+            if (target.type === "checkbox") {
+                value = target.checked;
+            } else if (target.type === "number") {
+                value = target.valueAsNumber;
+            } else {
+                value = target.value;
+            }
+            const name = target.name;
+            setFieldValue(name, value, validateOnChange);
+            setFieldTouched(name, true);
+        },
+        [setFieldValue, setFieldTouched, validateOnChange]
+    );
+
+    const handleBlur = useCallback((event: React.FocusEvent) => {
+        const target = event.target as HTMLInputElement;
+        const name = target.name;
+        setFieldTouched(name, true);
+    }, [setFieldTouched]);
+
+    const submit = useCallback(
+        async (e?: React.FormEvent<HTMLFormElement>) => {
+            e?.preventDefault();
+            e?.stopPropagation();
+            setIsSubmitting(true);
+            setSubmitCount((prev: number) => prev + 1);
+            const validationErrors = await validation?.(valuesRef.current);
+            if (validationErrors && Object.keys(validationErrors).length > 0) {
+                setErrors(validationErrors);
+            } else {
+                setErrors({});
+                await onSubmit?.(valuesRef.current, controllerRef.current);
+            }
+            setIsSubmitting(false);
+            setVersion((prev: number) => prev + 1);
+        },
+        [onSubmit, validation]
+    );
+
+    const resetForm = useCallback((props?: FormexResetProps<T>) => {
+        const {
+            submitCount: submitCountProp,
+            values: valuesProp,
+            errors: errorsProp,
+            touched: touchedProp
+        } = props ?? {};
+        valuesRef.current = valuesProp ?? initialValuesRef.current;
+        initialValuesRef.current = valuesProp ?? initialValuesRef.current;
+        setValuesInner(valuesProp ?? initialValuesRef.current);
+        setErrors(errorsProp ?? {});
+        setTouchedState(touchedProp ?? initialTouched ?? {});
+        setDirty(false);
+        setSubmitCount(submitCountProp ?? 0);
+        setVersion((prev: number) => prev + 1);
+        onReset?.(controllerRef.current);
+        // Reset history with refs
+        historyRef.current = [valuesProp ?? initialValuesRef.current];
+        historyIndexRef.current = 0;
+    }, [onReset, initialTouched]);
+
+    useEffect(() => {
+        if (!equal(initialValuesRef.current, initialValues)) {
+            resetForm({ values: initialValues });
+        }
+    }, [initialValues, resetForm]);
+
+    const undo = useCallback(() => {
+        if (historyIndexRef.current > 0) {
+            const newIndex = historyIndexRef.current - 1;
+            const newValues = historyRef.current[newIndex];
+            setValuesInner(newValues);
+            valuesRef.current = newValues;
+            historyIndexRef.current = newIndex;
+            setDirty(!equal(initialValuesRef.current, newValues));
+            callDebouncedOnValuesChange(newValues);
+        }
+    }, [callDebouncedOnValuesChange]);
+
+    const redo = useCallback(() => {
+        if (historyIndexRef.current < historyRef.current.length - 1) {
+            const newIndex = historyIndexRef.current + 1;
+            const newValues = historyRef.current[newIndex];
+            setValuesInner(newValues);
+            valuesRef.current = newValues;
+            historyIndexRef.current = newIndex;
+            setDirty(!equal(initialValuesRef.current, newValues));
+            callDebouncedOnValuesChange(newValues);
+        }
+    }, [callDebouncedOnValuesChange]);
+
+    const controllerRef = useRef<FormexController<T>>({} as FormexController<T>);
+
+    const controller = useMemo<FormexController<T>>(
+        () => ({
+            values,
+            initialValues: initialValuesRef.current,
+            handleChange,
+            isSubmitting,
+            setSubmitting: setIsSubmitting,
+            setValues,
+            setFieldValue,
+            errors,
+            setFieldError,
+            touched: touchedState,
+            setFieldTouched,
+            setTouched: setTouchedState,
+            dirty,
+            setDirty,
+            handleSubmit: submit,
+            submitCount,
+            setSubmitCount,
+            handleBlur,
+            validate,
+            isValidating,
+            resetForm,
+            version,
+            debugId: debugIdRef.current,
+            undo,
+            redo,
+            canUndo: historyIndexRef.current > 0,
+            canRedo: historyIndexRef.current < historyRef.current.length - 1
+        }),
+        [
+            values,
+            errors,
+            touchedState,
+            dirty,
+            isSubmitting,
+            submitCount,
+            isValidating,
+            version,
+            handleChange,
+            handleBlur,
+            setValues,
+            setFieldValue,
+            setFieldTouched,
+            setTouchedState,
+            setFieldError,
+            validate,
+            submit,
+            resetForm,
+            undo,
+            redo
+        ]
+    );
+
+    useEffect(() => {
+        controllerRef.current = controller;
+    }, [controller]);
+
+    return controller;
+}

package/src/utils.ts

@@ -0,0 +1,102 @@
+/** @private is the value an empty array? */
+export const isEmptyArray = (value?: unknown) =>
+    Array.isArray(value) && value.length === 0;
+
+/** @private is the given object a Function? */
+
+export const isFunction = (obj: unknown): obj is Function =>
+    typeof obj === "function";
+
+/** @private is the given object an Object? */
+export const isObject = (obj: unknown): obj is Record<string, unknown> =>
+    obj !== null && typeof obj === "object";
+
+/** @private is the given object an integer? */
+export const isInteger = (obj: unknown): boolean =>
+    String(Math.floor(Number(obj))) === obj;
+
+/** @private is the given object a NaN? */
+
+export const isNaN = (obj: unknown): boolean => obj !== obj;
+
+/**
+ * Deeply get a value from an object via its path.
+ */
+export function getIn(
+    obj: unknown,
+    key: string | string[],
+    def?: unknown,
+    p = 0
+): unknown {
+    const path = toPath(key);
+    let current: unknown = obj;
+    while (current && p < path.length) {
+        current = (current as Record<string, unknown>)[path[p++]];
+    }
+
+    // check if path is not in the end
+    if (p !== path.length && !current) {
+        return def;
+    }
+
+    return current === undefined ? def : current;
+}
+
+export function setIn(obj: unknown, path: string, value: unknown): unknown {
+    const res = clone(obj) as Record<string, unknown>; // this keeps inheritance when obj is a class
+    let resVal: Record<string, unknown> = res;
+    let i = 0;
+    const pathArray = toPath(path);
+
+    for (; i < pathArray.length - 1; i++) {
+        const currentPath: string = pathArray[i];
+        const currentObj = getIn(obj, pathArray.slice(0, i + 1));
+
+        if (currentObj && (isObject(currentObj) || Array.isArray(currentObj))) {
+            resVal = resVal[currentPath] = clone(currentObj) as Record<string, unknown>;
+        } else {
+            const nextPath: string = pathArray[i + 1];
+            resVal = resVal[currentPath] =
+                (isInteger(nextPath) && Number(nextPath) >= 0 ? [] : {}) as Record<string, unknown>;
+        }
+    }
+
+    // Return original object if new value is the same as current
+    if ((i === 0 ? (obj as Record<string, unknown>) : resVal)[pathArray[i]] === value) {
+        return obj;
+    }
+
+    if (value === undefined) {
+        delete resVal[pathArray[i]];
+    } else {
+        resVal[pathArray[i]] = value;
+    }
+
+    // If the path array has a single element, the loop did not run.
+    // Deleting on `resVal` had no effect in this scenario, so we delete on the result instead.
+    if (i === 0 && value === undefined) {
+        delete res[pathArray[i]];
+    }
+
+    return res;
+}
+
+export function clone(value: unknown): unknown {
+    if (Array.isArray(value)) {
+        return [...value];
+    } else if (typeof value === "object" && value !== null) {
+        // Preserve class instances (EntityReference, GeoPoint, etc.) - don't spread them
+        if (Object.getPrototypeOf(value) !== Object.prototype) {
+            return value;
+        }
+        return { ...(value as Record<string, unknown>) };
+    } else {
+        return value; // This is for primitive types which do not need cloning.
+    }
+}
+
+function toPath(value: string | string[]) {
+    if (Array.isArray(value)) return value; // Already in path array form.
+    // Replace brackets with dots, remove leading/trailing dots, then split by dot.
+    return value.replace(/\[(\d+)]/g, ".$1").replace(/^\./, "").replace(/\.$/, "").split(".");
+}