@rebasepro/formex 0.0.1-canary.0

package/package.json

@@ -0,0 +1,78 @@
+{
+    "name": "@rebasepro/formex",
+    "type": "module",
+    "version": "0.0.1-canary.0",
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "firebase",
+        "cms",
+        "admin",
+        "admin panel",
+        "firebase panel",
+        "firestore",
+        "headless",
+        "headless cms",
+        "content manager"
+    ],
+    "exports": {
+        ".": {
+            "development": "./src/index.ts",
+            "import": "./dist/index.es.js",
+            "require": "./dist/index.umd.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./package.json": "./package.json"
+    },
+    "main": "./dist/index.umd.js",
+    "module": "./dist/index.es.js",
+    "types": "dist/index.d.ts",
+    "source": "src/index.ts",
+    "peerDependencies": {
+        "react": ">=19.0.0",
+        "react-dom": ">=19.0.0"
+    },
+    "dependencies": {
+        "fast-equals": "5.3.0"
+    },
+    "devDependencies": {
+        "@jest/globals": "^30.2.0",
+        "@types/jest": "^29.5.14",
+        "@types/node": "^20.19.17",
+        "@types/react": "^19.0.8",
+        "@types/react-dom": "^19.0.3",
+        "babel-plugin-react-compiler": "^19.0.0-beta-af1b7da-20250417",
+        "eslint-plugin-react-compiler": "^19.1.0-rc.2",
+        "jest": "^29.7.0",
+        "ts-jest": "^29.4.5",
+        "typescript": "^5.9.3",
+        "vite": "^7.2.4"
+    },
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+        "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",
+        "test": "jest --passWithNoTests"
+    },
+    "files": [
+        "dist",
+        "src",
+        "bin"
+    ],
+    "jest": {
+        "transform": {
+            "^.+\\.tsx?$": "ts-jest"
+        },
+        "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$",
+        "moduleFileExtensions": [
+            "ts",
+            "tsx",
+            "js",
+            "jsx",
+            "json",
+            "node"
+        ]
+    },
+    "gitHead": "646afae9c387c3ce02c699d98cd8c7272bdd1929"
+}

package/src/Field.tsx

@@ -0,0 +1,158 @@
+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 = any> {
+    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<any>;
+
+    /**
+     * 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?: any;
+
+    /** Inner ref */
+    innerRef?: (instance: any) => 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<any>, formex: FormexController<any>): FieldInputProps<any> => {
+    const isAnObject = isObject(nameOrOptions);
+    const name = isAnObject
+        ? (nameOrOptions as FieldConfig<any>).name
+        : nameOrOptions;
+    const valueState = getIn(formex.values, name);
+
+    const field: FieldInputProps<any> = {
+        name,
+        value: valueState,
+        onChange: formex.handleChange,
+        onBlur: formex.handleBlur,
+    };
+    if (isAnObject) {
+        const {
+            type,
+            value: valueProp, // value is special for checkboxes
+            as: is,
+            multiple,
+        } = nameOrOptions as FieldConfig<any>;
+
+        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,10 @@
+import React, { useContext } from "react";
+import { FormexController } from "./types";
+
+const FormexContext = React.createContext<FormexController<any>>({} as any);
+
+export const useFormex = <T extends object>() => useContext<FormexController<T>>(FormexContext);
+
+export const Formex = ({ value, children }: { value: FormexController<any>, 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 extends object> = {
+    values: T;
+    initialValues: T;
+    setValues: (values: T) => void;
+    setFieldValue: (key: string, value: any, 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 extends object> = {
+    values?: T;
+    submitCount?: number;
+    errors?: Record<string, string>;
+    touched?: Record<string, boolean>;
+};

package/src/useCreateFormex.tsx

@@ -0,0 +1,291 @@
+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 extends object>({
+    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<any>(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: any, shouldValidate?: boolean) => {
+            const newValues = setIn(valuesRef.current, key, value);
+            valuesRef.current = newValues;
+            setValuesInner(newValues);
+            if (!equal(getIn(initialValuesRef.current, 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) => {
+            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) => ({
+                ...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) => 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) => 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) => prev + 1);
+        onReset?.(controllerRef.current);
+        // Reset history with refs
+        historyRef.current = [valuesProp ?? initialValuesRef.current];
+        historyIndexRef.current = 0;
+    }, [onReset, initialTouched]);
+
+    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,100 @@
+/** @private is the value an empty array? */
+export const isEmptyArray = (value?: any) =>
+    Array.isArray(value) && value.length === 0;
+
+/** @private is the given object a Function? */
+export const isFunction = (obj: any): obj is Function =>
+    typeof obj === "function";
+
+/** @private is the given object an Object? */
+export const isObject = (obj: any): obj is Object =>
+    obj !== null && typeof obj === "object";
+
+/** @private is the given object an integer? */
+export const isInteger = (obj: any): boolean =>
+    String(Math.floor(Number(obj))) === obj;
+
+/** @private is the given object a NaN? */
+// eslint-disable-next-line no-self-compare
+export const isNaN = (obj: any): boolean => obj !== obj;
+
+/**
+ * Deeply get a value from an object via its path.
+ */
+export function getIn(
+    obj: any,
+    key: string | string[],
+    def?: any,
+    p = 0
+) {
+    const path = toPath(key);
+    while (obj && p < path.length) {
+        obj = obj[path[p++]];
+    }
+
+    // check if path is not in the end
+    if (p !== path.length && !obj) {
+        return def;
+    }
+
+    return obj === undefined ? def : obj;
+}
+
+export function setIn(obj: any, path: string, value: any): any {
+    const res: any = clone(obj); // this keeps inheritance when obj is a class
+    let resVal: any = res;
+    let i = 0;
+    const pathArray = toPath(path);
+
+    for (; i < pathArray.length - 1; i++) {
+        const currentPath: string = pathArray[i];
+        const currentObj: any = getIn(obj, pathArray.slice(0, i + 1));
+
+        if (currentObj && (isObject(currentObj) || Array.isArray(currentObj))) {
+            resVal = resVal[currentPath] = clone(currentObj);
+        } else {
+            const nextPath: string = pathArray[i + 1];
+            resVal = resVal[currentPath] =
+                isInteger(nextPath) && Number(nextPath) >= 0 ? [] : {};
+        }
+    }
+
+    // Return original object if new value is the same as current
+    if ((i === 0 ? obj : 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: any) {
+    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 };
+    } 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(".");
+}