@react-fabric/form 1.0.0-beta.8 → 1.0.1

package/src/form/Form.tsx

@@ -21,24 +21,14 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import { yupResolver } from "@hookform/resolvers/yup";
 import { useDebounce } from "@react-fabric/core";
-import { type yup } from "@react-fabric/utilities";
-import {
-  useCallback,
-  useEffect,
-  useImperativeHandle,
-  useRef,
-  useTransition,
-  type PropsWithChildren,
-  type Ref,
-} from "react";
-import {
-  FormProvider,
-  useForm,
-  type DefaultValues,
-  type FormState,
-} from "react-hook-form";
+import { EMPTY_OBJECT } from "@react-fabric/utilities";
+import { useCallback, useEffect, useImperativeHandle, useRef, useTransition, type PropsWithChildren, type Ref } from "react";
+import { FormProvider, useForm as useFormHook, type FormState, type Path, type Resolver } from "react-hook-form";
+
+type NestedKeyOf<T extends object> = {
+  [K in keyof T & (string | number)]: T[K] extends object ? `${K}` | `${K}.${NestedKeyOf<T[K]>}` : K;
+}[keyof T & (string | number)];
 
 export interface FormRef<K extends KeyValue> {
   state: FormState<K>;
@@ -47,20 +37,25 @@ export interface FormRef<K extends KeyValue> {
   submit: () => void;
   validate: () => Promise<boolean>;
   getValues: () => K;
-  setValue: (key: keyof K, value: AnyObject) => void;
+  setValue: (key: NestedKeyOf<K>, value: unknown) => void;
   setValues: (values: K) => void;
 }
 
 export interface FormProps<K extends KeyValue = KeyValue> {
   formRef?: Ref<FormRef<K>>;
   /**
-   * form data schema
+   * react-hook-form resolver for validation
+   * @see {@link https://react-hook-form.com/ts#Resolver}
    */
-  schema?: yup.ObjectSchema<K>;
+  resolver?: Resolver<K>;
   /**
    * default data values
    */
-  defaultValues?: K;
+  defaultValues?: K | Promise<K>;
+  /**
+   * reset values on defaultValues change (workaround for using fetch result)
+   */
+  resetOnChange?: boolean;
   /**
    * change callback
    */
@@ -73,42 +68,72 @@ export interface FormProps<K extends KeyValue = KeyValue> {
 
 const DEFAULT_SUBMIT = () => undefined;
 
-export const Form = <K extends KeyValue>({
+/**
+ * Form component for managing form state and validation using react-hook-form and yup.
+ * It provides a simple interface for form handling, including submission, validation, and value management.
+ * It supports nested form structures and allows for custom validation schemas using Yup.
+ *
+ * @example
+ * ```jsx
+ * <Form
+ *   formRef={formRef}
+ *   resolver={hookformResolver(schema)}
+ *   defaultValues={{ name: "", email: "" }}
+ *   onSubmit={(values) => {
+ *     console.log("Form submitted with values:", values);
+ *   }}
+ * >
+ *   <input name="name" ref={form.register} placeholder="Name" />
+ *   <input name="email" ref={form.register} placeholder="Email" />
+ *   <button type="submit">Submit</button>
+ * </Form>
+ * ```
+ *
+ * @see {@link https://react-hook-form.com/docs/useform} for more details on the properties.
+ */
+export function Form<K extends KeyValue>({
   formRef,
-  schema,
+  resolver,
   children,
-  defaultValues,
+  resetOnChange,
+  defaultValues = EMPTY_OBJECT as K,
   onSubmit = DEFAULT_SUBMIT,
   onChange,
   ...rest
-}: PropsWithChildren<FormProps<K>>) => {
+}: PropsWithChildren<FormProps<K>>) {
   const ref = useRef<HTMLFormElement>(null);
-  const form = useForm<K>({
+  const form = useFormHook<K>({
     shouldFocusError: true,
-    resolver: schema && (yupResolver(schema) as AnyObject),
-    defaultValues: defaultValues as DefaultValues<K>,
+    resolver,
+    defaultValues: async () => await Promise.resolve(defaultValues),
   });
 
   const [, startTransition] = useTransition();
-  const changeHandler = useDebounce(onChange, [onChange]);
+  const changeHandler = useDebounce(onChange, [onChange], 300);
   useEffect(() => {
     const subscription = form.watch((value) => {
-      startTransition(() => changeHandler?.(value as K));
+      startTransition(() => changeHandler?.(value));
     });
     return () => subscription.unsubscribe();
-  }, [form.watch, changeHandler]);
+  }, [form.watch, changeHandler, form]);
 
   const handleReset = useCallback(
-    (reset: AnyObject = {}) => {
-      form.reset(reset);
-      form.clearErrors();
-      ref.current
-        ?.querySelector<HTMLElement>("[auto-focus], input, textarea")
-        ?.focus();
+    (reset: K | Promise<K> = {} as K) => {
+      void Promise.resolve(reset).then((resp) => {
+        form.reset(resp);
+        form.clearErrors();
+        ref.current?.querySelector<HTMLElement>("[auto-focus], input, textarea")?.focus();
+      });
     },
-    [defaultValues],
+    [form],
   );
 
+  useEffect(() => {
+    if (resetOnChange) {
+      handleReset(defaultValues);
+    }
+  }, [defaultValues, handleReset, resetOnChange]);
+
   useImperativeHandle(
     formRef,
     () => ({
@@ -116,12 +141,13 @@ export const Form = <K extends KeyValue>({
       reset: () => handleReset(defaultValues),
       clear: () => handleReset(),
       submit: () => form.handleSubmit(onSubmit),
-      validate: async () => await form.trigger(),
+      validate: async (fields?: Array<Path<K>>) => await form.trigger(fields),
       getValues: () => form.getValues(),
       setValues: (v) => setTimeout(() => form.reset(v), 50),
       setValue: (k, v) =>
         setTimeout(
           () =>
+            // @ts-expect-error ignore
             form.setValue(k as AnyObject, v, {
               shouldDirty: false,
               shouldTouch: false,
@@ -129,18 +155,13 @@ export const Form = <K extends KeyValue>({
           50,
         ),
     }),
-    [onSubmit, form, form.formState, defaultValues],
+    [defaultValues, form, handleReset, onSubmit],
   );
 
-  const onInvalid = useCallback((_: AnyObject, e: AnyObject) => {
-    const el = e.target;
+  const onInvalid = useCallback((_: AnyObject, e?: React.BaseSyntheticEvent) => {
+    const el = e?.target as HTMLFormElement;
     setTimeout(
-      () =>
-        el
-          .querySelector(
-            "input[aria-invalid='true'],textarea[aria-invalid='true']",
-          )
-          ?.focus(),
+      () => el?.querySelector<HTMLInputElement>("input[aria-invalid='true'],textarea[aria-invalid='true']")?.focus(),
       10,
     );
   }, []);
@@ -150,7 +171,10 @@ export const Form = <K extends KeyValue>({
       <form
         ref={ref}
         onReset={() => handleReset(defaultValues)}
-        onSubmit={form.handleSubmit(onSubmit, onInvalid) as AnyObject}
+        onSubmit={(e) => {
+          e.stopPropagation();
+          void form.handleSubmit(onSubmit, onInvalid)(e);
+        }}
         data-loading={form.formState.isSubmitting}
         className="contents"
         autoComplete="off"
@@ -161,4 +185,4 @@ export const Form = <K extends KeyValue>({
       </form>
     </FormProvider>
   );
-};
+}

package/src/form/useForm.ts

@@ -0,0 +1,53 @@
+/*
+ * React Fabric
+ * @version: 1.0.0
+ *
+ *
+ * The MIT License (MIT)
+ * Copyright (c) 2026 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ * and associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+ * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+import type { FieldValues, UseFormReturn } from "react-hook-form";
+import { useFormContext, useWatch } from "react-hook-form";
+
+export type UseCustomFormReturn<K extends FieldValues = FieldValues> = Pick<
+  UseFormReturn<K>,
+  "formState" | "getValues" | "setValue" | "watch" | "reset" | "resetField" | "setError" | "setFocus"
+> & {
+  values: K;
+  watch: UseFormReturn<K>["watch"];
+};
+
+export function useForm<K extends KeyValue = KeyValue>(): UseCustomFormReturn<K> {
+  const { formState, getValues, setValue, watch, reset, resetField, setError, setFocus } = useFormContext<K>();
+  const values = useWatch<K>();
+
+  return {
+    values: {
+      ...values,
+      ...getValues(),
+    },
+    formState,
+    getValues,
+    setValue,
+    watch,
+    reset,
+    resetField,
+    setError,
+    setFocus,
+  };
+}

package/src/hooks/useFileUploader.ts

@@ -22,13 +22,10 @@
  */
 
 import { isArray, isObject, isString, uuid } from "@react-fabric/utilities";
-import { type AxiosRequestConfig } from "axios";
-import { useCallback, useReducer } from "react";
+import type { AxiosRequestConfig } from "axios";
+import { useCallback, useEffect, useReducer } from "react";
 
-export type UploadHandler = (
-  data: FormData,
-  config: AxiosRequestConfig,
-) => Promise<string>;
+export type UploadHandler = (data: FormData, config: AxiosRequestConfig) => Promise<string>;
 
 interface FileInfo {
   key: string;
@@ -54,14 +51,42 @@ type UploaderActions =
   | { type: "stop"; key: string; path: string }
   | { type: "error"; key: string; error: string }
   | { type: "progress"; key: string; progress: number }
+  | { type: "init"; initialList?: string | FileInfo | FileInfo[] }
   | { type: "remove"; key: string }
   | { type: "abort"; key: string };
 
-export const useFileUploader = (
+/**
+ * useFileUploader hook provides a way to handle file uploads
+ * with progress tracking, error handling, and file management.
+ * It uses a reducer to manage the state of uploaded files and their statuses.
+ *
+ * @param uploader - The function that handles the file upload.
+ * @param initialList - Initial list of files to be managed by the uploader.
+ * @param multiple - Whether to allow multiple file uploads or not.
+ * @returns An object containing methods to upload, remove, retry files,
+ *          and the current state of the uploader including pending uploads and file list.
+ *
+ * @example
+ * ```jsx
+ * const { upload, remove, retry, state } = useFileUploader(uploader, initialList, multiple);
+ * ```
+ */
+export function useFileUploader(
   uploader: UploadHandler,
   initialList?: string | FileInfo | FileInfo[],
-  multiple = true,
-) => {
+  {
+    multiple = true,
+    onChange,
+  }:
+    | {
+        multiple?: true;
+        onChange?: (files: FileInfo[] | null) => void;
+      }
+    | {
+        multiple: false;
+        onChange?: (files: FileInfo | null) => void;
+      } = {},
+) {
   const [state, dispatch] = useReducer(
     (state: UploaderState, action: UploaderActions) => {
       if (action.type === "start") {
@@ -72,7 +97,7 @@ export const useFileUploader = (
       if (action.type === "stop") {
         const fileObject = state.files.get(action.key);
         if (fileObject) {
-          const { progress, abort, ...rest } = fileObject;
+          const { progress: _, abort: __, ...rest } = fileObject;
           state.files.set(action.key, {
             ...rest,
             path: action.path,
@@ -84,7 +109,7 @@ export const useFileUploader = (
       if (action.type === "error") {
         const fileObject = state.files.get(action.key);
         if (fileObject) {
-          const { file, progress, abort, ...rest } = fileObject;
+          const { file: _, progress: __, abort: ___, ...rest } = fileObject;
           state.files.set(action.key, { ...rest, error: action.error });
         }
         state.count--;
@@ -103,6 +128,29 @@ export const useFileUploader = (
       if (action.type === "remove") {
         state.files.delete(action.key);
       }
+      if (action.type === "init") {
+        state.files = new Map();
+        if (isString(action.initialList)) {
+          const key = uuid();
+          state.files.set(key, {
+            key,
+            path: action.initialList,
+            filename: "",
+            size: 0,
+            mime: "",
+          });
+        }
+        if (isObject(action.initialList)) {
+          const key = uuid();
+          state.files.set(key, { ...(action.initialList as unknown as FileInfo), key });
+        }
+        if (isArray(action.initialList)) {
+          action.initialList.forEach((file) => {
+            const key = uuid();
+            state.files.set(key, { ...file, key });
+          });
+        }
+      }
       state.list = Array.from(state.files.values())
         .map((file) => {
           return (
@@ -118,81 +166,68 @@ export const useFileUploader = (
           );
         })
         .filter(Boolean) as FileInfo[];
+      if (action.type === "remove" || action.type === "stop") {
+        setTimeout(() => {
+          // @ts-expect-error ignore
+          onChange?.(multiple ? state.list : (state.list[0] ?? null));
+        }, 100);
+      }
       return { ...state };
     },
     {
       files: new Map(),
       count: 0,
     } as UploaderState,
-    (state: UploaderState) => {
-      if (initialList) {
-        if (isString(initialList)) {
-          const key = uuid();
-          state.files.set(key, {
-            key,
-            path: initialList,
-            filename: "",
-            size: 0,
-            mime: "",
-          });
-        }
-        if (isObject(initialList)) {
-          const key = uuid();
-          state.files.set(key, { ...(initialList as AnyObject), key });
-        }
-        if (isArray(initialList)) {
-          initialList.forEach((file) => {
-            const key = uuid();
-            state.files.set(key, { ...file, key });
-          });
-        }
-      }
-      state.list = Array.from(state.files.values());
-      return state;
-    },
   );
 
-  const doUpload = useCallback(async (key: string, file: File) => {
-    const data = new FormData();
-    data.append("file", file);
-    const abort = new AbortController();
-    dispatch({
-      type: "start",
-      key,
-      file: {
+  useEffect(() => {
+    dispatch({ type: "init", initialList });
+  }, [initialList]);
+
+  const doUpload = useCallback(
+    async (key: string, file: File) => {
+      const data = new FormData();
+      data.append("file", file);
+      const abort = new AbortController();
+      dispatch({
+        type: "start",
         key,
-        file,
-        progress: 0.001,
-        mime: file.type,
-        filename: file.name,
-        size: file.size,
-        abort: () => abort.abort(),
-      },
-    });
-    await uploader(data, {
-      signal: abort.signal,
-      onUploadProgress(progressEvent) {
-        dispatch({
-          type: "progress",
+        file: {
           key,
-          progress: progressEvent.progress ?? 0,
-        });
-      },
-    })
-      .then((path) => {
-        dispatch({ type: "stop", key, path });
+          file,
+          progress: 0.001,
+          mime: file.type,
+          filename: file.name,
+          size: file.size,
+          abort: () => abort.abort(),
+        },
+      });
+      await uploader(data, {
+        signal: abort.signal,
+        onUploadProgress(progressEvent) {
+          dispatch({
+            type: "progress",
+            key,
+            progress: progressEvent.progress ?? 0,
+          });
+        },
       })
-      .catch((error) => {
-        if (error.code === "ERR_CANCELED" || error.name === "AbortError") {
-          return dispatch({ type: "abort", key });
-        }
-        dispatch({
-          type: "error",
-          key,
-          error: error?.message ?? "form:fileUploadFailed",
+        .then((path) => {
+          dispatch({ type: "stop", key, path });
+        })
+        .catch((error: KeyValue) => {
+          if (error.code === "ERR_CANCELED" || error.name === "AbortError") {
+            return dispatch({ type: "abort", key });
+          }
+          dispatch({
+            type: "error",
+            key,
+            error: (error?.message as string) ?? "form:fileUploadFailed",
+          });
         });
-      });
-  }, []);
+    },
+    [uploader],
+  );
 
   const upload = useCallback(
     (files: FileList | null) => {
@@ -205,7 +240,7 @@ export const useFileUploader = (
           void doUpload(uuid(), file);
         });
     },
-    [multiple],
+    [doUpload, multiple, state.files],
   );
 
   const retry = useCallback(
@@ -213,22 +248,18 @@ export const useFileUploader = (
       const fileObject = state.files.get(key);
       void (fileObject?.file && doUpload(key, fileObject.file));
     },
-    [state],
+    [doUpload, state.files],
   );
 
-  const remove = useCallback(
-    (key: string) => {
-      dispatch({ type: "remove", key });
-    },
-    [state],
-  );
+  const remove = useCallback((key: string) => {
+    dispatch({ type: "remove", key });
+  }, []);
 
   return {
     upload,
     remove,
     retry,
     pending: state.count,
-    list: state.list,
     files: Array.from(state.files.values()),
   };
-};
+}