rfhook 1.0.1 → 1.1.1

package/README.md

@@ -4,12 +4,13 @@ A lightweight React hook for handling form submissions with advanced form data p
 
 ## Features
 
-- 🚀 **Simple API** - Just one hook to handle all your form needs
-- 🎯 **TypeScript Support** - Fully typed with generic support
-- 🔧 **Nested Objects** - Parse nested form data with dot notation (`user.name`)
-- 📋 **Array Support** - Handle arrays with indexed notation (`items[0]`)
-- 📦 **Lightweight** - Zero dependencies (except React)
-- 🎨 **Framework Agnostic** - Works with any form structure
+- :rocket: **Simple API** - Just one hook to handle all your form needs
+- :dart: **TypeScript Support** - Fully typed with generic support
+- :wrench: **Nested Objects** - Parse nested form data with dot notation (`user.name`)
+- :clipboard: **Array Support** - Handle arrays with indexed notation (`items[0]`)
+- :floppy_disk: **Automatic Prevention** - Prevents default form submission behavior by default
+- :money_with_wings: **Lightweight** - Zero dependencies (except React)
+- :memo: **Framework Agnostic** - Works with any form structure
 
 ## Installation
 
@@ -37,19 +38,23 @@ interface FormData {
 }
 
 function LoginForm() {
-  const { ref, submit } = useForm<FormData>({
-    handleSubmit: (data) => {
+  const { ref, onSubmit } = useForm<FormData>({
+    submit: (data) => {
       console.log(data); // { email: "user@example.com", password: "secret" }
     }
   });
 
   return (
-    <form ref={ref} onSubmit={submit}>
+    <form ref={ref} onSubmit={onSubmit}>
       <input name="email" type="email" />
       <input name="password" type="password" />
       <button type="submit">Login</button>
     </form>
   );
+}
+      <button type="submit">Login</button>
+    </form>
+  );
 }
 ```
 
@@ -73,8 +78,8 @@ interface UserForm {
 }
 
 function UserForm() {
-  const { ref, submit } = useForm<UserForm>({
-    handleSubmit: (data) => {
+  const { ref, onSubmit } = useForm<UserForm>({
+    submit: (data) => {
       console.log(data);
       // {
       //   user: {
@@ -91,7 +96,7 @@ function UserForm() {
   });
 
   return (
-    <form ref={ref} onSubmit={submit}>
+    <form ref={ref} onSubmit={onSubmit}>
       <input name="user.profile.name" placeholder="Name" />
       <input name="user.profile.age" type="number" placeholder="Age" />
       <select name="user.preferences.theme">
@@ -117,8 +122,8 @@ interface TodoForm {
 }
 
 function TodoForm() {
-  const { ref, submit } = useForm<TodoForm>({
-    handleSubmit: (data) => {
+  const { ref, onSubmit } = useForm<TodoForm>({
+    submit: (data) => {
       console.log(data);
       // {
       //   todos: [
@@ -130,7 +135,7 @@ function TodoForm() {
   });
 
   return (
-    <form ref={ref} onSubmit={submit}>
+    <form ref={ref} onSubmit={onSubmit}>
       <input name="todos[0].title" placeholder="First todo" />
       <input name="todos[0].completed" type="checkbox" />
 
@@ -149,12 +154,59 @@ function TodoForm() {
 
 #### Parameters
 
-- `options.handleSubmit: (data: T) => void` - Callback function called when form is submitted
+- `options.submit: (data: T) => void` - Callback function called when form is submitted with parsed form data
 
 #### Returns
 
-- `ref: RefObject<HTMLFormElement>` - React ref to attach to your form element
-- `submit: (event: React.FormEvent) => void` - Submit handler to attach to form's `onSubmit`
+- `ref: React.RefObject<HTMLFormElement>` - React ref to attach to your form element
+- `onSubmit: (event: React.FormEvent<HTMLFormElement>) => void` - Form submission handler that prevents default behavior and calls submit with parsed data
+- `reset: () => void` - Resets the form to its initial state
+- `getFormData: () => T | null` - Gets current form data without triggering submission (returns null if form ref is not available)
+- `setValue: (name: string, value: string) => void` - Sets the value of a specific form field by name
+
+### Additional Usage Examples
+
+#### Using Form Utilities
+
+```tsx
+function MyForm() {
+  const form = useForm<FormData>({
+    submit: (data) => console.log('Submitted:', data)
+  });
+
+  const handleReset = () => {
+    form.reset(); // Reset form to initial state
+  };
+
+  const handlePreview = () => {
+    const currentData = form.getFormData();
+    if (currentData) {
+      console.log('Current form data:', currentData);
+    }
+  };
+
+  const handlePrefill = () => {
+    form.setValue('email', 'user@example.com');
+    form.setValue('name', 'John Doe');
+  };
+
+  return (
+    <>
+      <form ref={form.ref} onSubmit={form.onSubmit}>
+        <input name="name" placeholder="Name" />
+        <input name="email" type="email" placeholder="Email" />
+        <button type="submit">Submit</button>
+      </form>
+
+      <div>
+        <button onClick={handleReset}>Reset Form</button>
+        <button onClick={handlePreview}>Preview Data</button>
+        <button onClick={handlePrefill}>Prefill Form</button>
+      </div>
+    </>
+  );
+}
+```
 
 ### Form Data Parsing Rules
 
@@ -182,8 +234,8 @@ interface ContactData {
 }
 
 function ContactForm() {
-  const { ref, submit } = useForm<ContactData>({
-    handleSubmit: async (data) => {
+  const { ref, onSubmit } = useForm<ContactData>({
+    submit: async (data) => {
       try {
         const response = await fetch('/api/contact', {
           method: 'POST',
@@ -201,7 +253,7 @@ function ContactForm() {
   });
 
   return (
-    <form ref={ref} onSubmit={submit}>
+    <form ref={ref} onSubmit={onSubmit}>
       <input name="name" placeholder="Your Name" required />
       <input name="email" type="email" placeholder="Your Email" required />
       <textarea name="message" placeholder="Your Message" required />

package/dist/index.cjs

@@ -49,17 +49,70 @@ function parseFormData(formData) {
     return result;
 }
 
-function useForm({ handleSubmit }) {
+/**
+ * A React hook for handling form state and submission
+ *
+ * @template T - The expected shape of the parsed form data
+ * @param options - Configuration options for the form
+ * @returns Object containing form ref, handlers, and utility functions
+ *
+ * @example
+ * ```typescript
+ * interface LoginData {
+ *   email: string;
+ *   password: string;
+ * }
+ *
+ * const form = useForm<LoginData>({
+ *   submit: (data) => console.log(data.email, data.password)
+ * });
+ *
+ * return (
+ *   <form ref={form.ref} onSubmit={form.onSubmit}>
+ *     <input name="email" type="email" />
+ *     <input name="password" type="password" />
+ *     <button type="submit">Login</button>
+ *   </form>
+ * );
+ * ```
+ */
+function useForm({ submit }) {
     const ref = react.useRef(null);
-    const submit = (event) => {
+    const onSubmit = (event) => {
         event.preventDefault();
         if (!ref.current)
             return;
         const formData = new FormData(ref.current);
         const data = parseFormData(formData);
-        handleSubmit(data);
+        submit(data);
+    };
+    const reset = () => {
+        if (!ref.current)
+            return;
+        ref.current.reset();
+    };
+    const getFormData = () => {
+        if (!ref.current)
+            return null;
+        const formData = new FormData(ref.current);
+        const data = parseFormData(formData);
+        return data;
+    };
+    const setValue = (name, value) => {
+        if (!ref.current)
+            return;
+        const element = ref.current.elements.namedItem(name);
+        if (element && 'value' in element) {
+            element.value = value;
+        }
+    };
+    return {
+        ref,
+        onSubmit,
+        reset,
+        getFormData,
+        setValue
     };
-    return { ref, submit };
 }
 
 exports.useForm = useForm;

package/dist/index.js

@@ -47,17 +47,70 @@ function parseFormData(formData) {
     return result;
 }
 
-function useForm({ handleSubmit }) {
+/**
+ * A React hook for handling form state and submission
+ *
+ * @template T - The expected shape of the parsed form data
+ * @param options - Configuration options for the form
+ * @returns Object containing form ref, handlers, and utility functions
+ *
+ * @example
+ * ```typescript
+ * interface LoginData {
+ *   email: string;
+ *   password: string;
+ * }
+ *
+ * const form = useForm<LoginData>({
+ *   submit: (data) => console.log(data.email, data.password)
+ * });
+ *
+ * return (
+ *   <form ref={form.ref} onSubmit={form.onSubmit}>
+ *     <input name="email" type="email" />
+ *     <input name="password" type="password" />
+ *     <button type="submit">Login</button>
+ *   </form>
+ * );
+ * ```
+ */
+function useForm({ submit }) {
     const ref = useRef(null);
-    const submit = (event) => {
+    const onSubmit = (event) => {
         event.preventDefault();
         if (!ref.current)
             return;
         const formData = new FormData(ref.current);
         const data = parseFormData(formData);
-        handleSubmit(data);
+        submit(data);
+    };
+    const reset = () => {
+        if (!ref.current)
+            return;
+        ref.current.reset();
+    };
+    const getFormData = () => {
+        if (!ref.current)
+            return null;
+        const formData = new FormData(ref.current);
+        const data = parseFormData(formData);
+        return data;
+    };
+    const setValue = (name, value) => {
+        if (!ref.current)
+            return;
+        const element = ref.current.elements.namedItem(name);
+        if (element && 'value' in element) {
+            element.value = value;
+        }
+    };
+    return {
+        ref,
+        onSubmit,
+        reset,
+        getFormData,
+        setValue
     };
-    return { ref, submit };
 }
 
 export { useForm };

package/dist/useForm.hook.d.ts

@@ -1,8 +1,51 @@
-interface UseForm<T> {
-    handleSubmit: (data: T) => void;
+/**
+ * Configuration options for the useForm hook
+ */
+interface UseFormOptions<T> {
+    /** Callback function called when form is submitted with parsed form data */
+    submit: (data: T) => void;
 }
-export declare function useForm<T = object>({ handleSubmit }: UseForm<T>): {
-    ref: import("react").RefObject<HTMLFormElement | null>;
-    submit: (event: React.FormEvent) => void;
-};
+/**
+ * Return type of the useForm hook
+ */
+interface UseFormReturn<T> {
+    /** React ref to be attached to the form element */
+    ref: React.RefObject<HTMLFormElement | null>;
+    /** Form submission handler - prevents default and calls submit with parsed data */
+    onSubmit: (event: React.FormEvent<HTMLFormElement>) => void;
+    /** Resets the form to its initial state */
+    reset: () => void;
+    /** Gets current form data without triggering submission */
+    getFormData: () => T | null;
+    /** Sets the value of a specific form field by name */
+    setValue: (name: string, value: string) => void;
+}
+/**
+ * A React hook for handling form state and submission
+ *
+ * @template T - The expected shape of the parsed form data
+ * @param options - Configuration options for the form
+ * @returns Object containing form ref, handlers, and utility functions
+ *
+ * @example
+ * ```typescript
+ * interface LoginData {
+ *   email: string;
+ *   password: string;
+ * }
+ *
+ * const form = useForm<LoginData>({
+ *   submit: (data) => console.log(data.email, data.password)
+ * });
+ *
+ * return (
+ *   <form ref={form.ref} onSubmit={form.onSubmit}>
+ *     <input name="email" type="email" />
+ *     <input name="password" type="password" />
+ *     <button type="submit">Login</button>
+ *   </form>
+ * );
+ * ```
+ */
+export declare function useForm<T = Record<string, unknown>>({ submit }: UseFormOptions<T>): UseFormReturn<T>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rfhook",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "",
   "main": "dist/index.cjs",
   "module": "dist/index.js",

package/src/useForm.hook.ts

@@ -2,24 +2,110 @@ import { useRef } from 'react';
 
 import { parseFormData } from './utils/parseFormData';
 
-interface UseForm<T> {
-  handleSubmit: (data: T) => void;
+/**
+ * Configuration options for the useForm hook
+ */
+interface UseFormOptions<T> {
+  /** Callback function called when form is submitted with parsed form data */
+  submit: (data: T) => void;
 }
 
-export function useForm<T = object>({ handleSubmit }: UseForm<T>) {
+/**
+ * Form element types that can have their values set programmatically
+ */
+type FormElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+
+/**
+ * Return type of the useForm hook
+ */
+interface UseFormReturn<T> {
+  /** React ref to be attached to the form element */
+  ref: React.RefObject<HTMLFormElement | null>;
+  /** Form submission handler - prevents default and calls submit with parsed data */
+  onSubmit: (event: React.FormEvent<HTMLFormElement>) => void;
+  /** Resets the form to its initial state */
+  reset: () => void;
+  /** Gets current form data without triggering submission */
+  getFormData: () => T | null;
+  /** Sets the value of a specific form field by name */
+  setValue: (name: string, value: string) => void;
+}
+
+/**
+ * A React hook for handling form state and submission
+ *
+ * @template T - The expected shape of the parsed form data
+ * @param options - Configuration options for the form
+ * @returns Object containing form ref, handlers, and utility functions
+ *
+ * @example
+ * ```typescript
+ * interface LoginData {
+ *   email: string;
+ *   password: string;
+ * }
+ *
+ * const form = useForm<LoginData>({
+ *   submit: (data) => console.log(data.email, data.password)
+ * });
+ *
+ * return (
+ *   <form ref={form.ref} onSubmit={form.onSubmit}>
+ *     <input name="email" type="email" />
+ *     <input name="password" type="password" />
+ *     <button type="submit">Login</button>
+ *   </form>
+ * );
+ * ```
+ */
+export function useForm<T = Record<string, unknown>>(
+  { submit }: UseFormOptions<T>
+): UseFormReturn<T> {
   const ref = useRef<HTMLFormElement>(null);
 
-  const submit = (event: React.FormEvent) => {
+  const onSubmit = (event: React.FormEvent<HTMLFormElement>) => {
       event.preventDefault();
 
-      if (!ref.current) return
+      if (!ref.current) return;
 
       const formData = new FormData(ref.current);
 
-      const data: object = parseFormData(formData);
+      const data = parseFormData(formData) as T;
+
+      submit(data);
+    }
+
+  const reset = () => {
+    if (!ref.current) return;
+
+    ref.current.reset();
+  };
+
+  const getFormData = (): T | null => {
+    if (!ref.current) return null;
+
+    const formData = new FormData(ref.current);
+
+    const data = parseFormData(formData) as T;
+
+    return data;
+  };
+
+  const setValue = (name: string, value: string) => {
+    if (!ref.current) return;
+
+    const element = ref.current.elements.namedItem(name) as FormElement | null;
 
-      handleSubmit(data as T);
+    if (element && 'value' in element) {
+      element.value = value;
     }
+  };
 
-  return { ref, submit };
+  return {
+    ref,
+    onSubmit,
+    reset,
+    getFormData,
+    setValue
+  };
 }