update README, package.json, and TypeScript types; enhance form handling and validation

Author: Naim-pimjo

README.md

@@ -1,87 +1,137 @@
-
 # Formbold-react — The easiest way to configure and use Form in React/Next.js
 React package for [FormBold](https://formbold.com/) which simplifies the integration of FormBold with React/Next.js projects.
 
 FormBold is a multipurpose form API and serverless backend solution compatible with all hosting, SSG, and frameworks. It allows you to receive form submissions directly in your email, slack, telegram, notion, and more. It's ready for use with any Static, Jamstack, and SSG sites, such as HTML, React, Next.js, Gatsby, Vue, Nuxt, Hugo, and Jekyll.
 
 It offers a wide range of form fields, advanced features like conditional logic, and seamless integration with other tools.
 
+It helps you wire a form to FormBold with a small API, built-in validation for required fields, custom error messages, and basic submission state.
+
 ## Installation
 
 ```bash
 npm install formbold-react
 ```
 
-or
-
 ```bash
 yarn add formbold-react
 ```
 
-## Usages
-
-To use it you have to import it in your Form component. Then call it with the form_id. 
+## Usage
 
-And at the end, attach the handleSubmit function to the onSubmit event. 
+Import `useForm`, pass your FormBold `formId`, and attach the returned `handleSubmit` function to your form.
 
-```typescript
+```tsx
 import { useForm } from "formbold-react";
 
-function Form() {
+function ContactForm() {
   const [state, handleSubmit] = useForm("form_id");
 
   if (state.succeeded) {
-    return <div>Form submitted successfully</div>;
+    return <div>Form submitted successfully.</div>;
   }
 
   return (
-    <>
-      <h1>Home Page</h1>
-      <form onSubmit={handleSubmit}>
-        <label htmlFor="email">Email Address</label>
-        <input id="email" type="email" name="email" required />
-        <textarea id="message" name="message" required />
-        <button type="submit">{state.submitting ? "Submitting..." : "Submit"}</button>
-
-        <div>
-          {state.error && state.error.message}
-        </div>
-      </form>
-    </>
+    <form onSubmit={handleSubmit}>
+      <label htmlFor="email">Email Address</label>
+      <input id="email" type="email" name="email" required />
+
+      <label htmlFor="message">Message</label>
+      <textarea id="message" name="message" required />
+
+      <button type="submit">
+        {state.submitting ? "Submitting..." : "Submit"}
+      </button>
+
+      {state.error.status && <p>{state.error.message}</p>}
+    </form>
   );
 }
 
-export default Form;
+export default ContactForm;
 ```
 
-## Required fields
+## API
 
-To make certain fields mandatory in your form, you can use the `requiredFields` option when using the `useForm` hook. In the example below, the `email` field is set as a required field:
+### `useForm(formId, config?)`
 
-```typescript
-const [state, handleSubmit] = useForm("form_id", { requiredFields: ["email"] });
+```ts
+const [state, handleSubmit] = useForm("form_id", config);
 ```
-This ensures that the form cannot be submitted unless the `email` field is filled out by the user.
 
+Returns:
+
+```ts
+[
+  {
+    error: { message: string; status: boolean };
+    succeeded: boolean;
+    submitting: boolean;
+  },
+  (event, recaptchaRef?) => void
+]
+```
+
+### `config`
 
-## Custom error messages
-You can customize the error messages displayed when certain fields are not filled out in your form. By using the `errorMessages` option in the `useForm` hook, you can provide custom error messages for different scenarios. 
+```ts
+type Config = {
+  requiredFields?: string[];
+  errorMessages?: {
+    empty?: string;
+    required?: (fields: string[]) => string;
+  };
+};
+```
 
-Here's an example of how you can set custom error messages for the `name` and `email` fields:
+Example:
 
-```typescript
+```ts
 const [state, handleSubmit] = useForm("form_id", {
   requiredFields: ["name", "email"],
   errorMessages: {
     empty: "Please fill the form!",
     required: fields => `Please fill the required fields: ${fields.join(", ")}`,
-  }
+  },
+});
+```
+
+### Required fields
+
+Use `requiredFields` when you want the hook to block submission until specific inputs are filled.
+
+```ts
+const [state, handleSubmit] = useForm("form_id", {
+  requiredFields: ["email"],
 });
 ```
 
-Feel free to customize the error messages according to your specific requirements.
+### reCAPTCHA support
+
+If you use reCAPTCHA, pass the ref as the second argument to the submit handler.
+
+```tsx
+<form onSubmit={e => handleSubmit(e, recaptchaRef)}>
+```
 
+The hook will include `g-recaptcha-response` in the submitted payload when a ref is provided.
+
+## Behavior notes
+
+- Empty forms are rejected before the request is sent.
+- Required field validation runs before submission.
+- Non-2xx responses are treated as submission failures.
+- Repeated form fields are preserved as arrays in the request payload.
+
+## Types
+
+The package exports its public types from the root entry point:
+
+```ts
+import type { Config, ErrorState, CaptchaRef } from "formbold-react";
+```
 
-## ****Useful Links and Information****
+## Links
 
-For more information visit the [documentation](https://formbold.com/docs).
+- [FormBold docs](https://formbold.com/docs)
+- [FormBold homepage](https://formbold.com/)

package.json

@@ -1,12 +1,14 @@
 {
   "name": "formbold-react",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Formbold package for react.",
-  "main": "dist/index.js",
-  "types": "./dist/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    "types": "./dist/index.d.ts",
-    "default": "./dist/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "repository": {
     "type": "git",
@@ -17,6 +19,11 @@
   "scripts": {
     "build": "tsc --declaration"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
   "license": "MIT",
   "keywords": [
     "forms",
@@ -28,13 +35,11 @@
     "formbold"
   ],
   "devDependencies": {
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "^19.0.0",
     "typescript": "^5.8.2"
   },
   "peerDependencies": {
-    "@types/react": "^19.0.0",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6"
+    "react": "^18.0.0 || ^19.0.0"
   },
   "bugs": {
     "url": "https://github.com/FormBold/formbold-react/issues"

src/index.ts

@@ -1 +1,9 @@
 export { useForm } from "./useForm";
+export type {
+  CaptchaRef,
+  Config,
+  DeepRequired,
+  ErrorMessages,
+  ErrorState,
+  FormValues,
+} from "./types";

src/types.ts

@@ -2,49 +2,59 @@
  * Error state for the useForm hook.
  */
 export type ErrorState = {
-    /** The error message */
-    message: string;
-    /** The error status */
-    status: boolean;
-  };
-  
+  /** The error message */
+  message: string;
+  /** The error status */
+  status: boolean;
+};
+
+/**
+ * Error messages for the useForm hook.
+ */
+export type ErrorMessages = {
+  /** Error message when the form is empty */
+  empty?: string;
+  /** Error message when the required fields are empty */
+  required?: (fields: string[]) => string;
+};
+
+/**
+ * Configuration options for the useForm hook.
+ */
+export type Config = {
   /**
-   * Error messages for the useForm hook.
+   * Custom error messages
+   *
+   * @example
+   * errorMessages: {
+   *  empty: 'Oops the form is empty!',
+   *  required: fields => `You missed: ${fields.join(', ')}`,
+   * }
    */
-  export type ErrorMessages = {
-    /** Error message when the form is empty */
-    empty?: string;
-    /** Error message when the required fields are empty */
-    required?: (fields: string[]) => string;
-  };
-  
+  errorMessages?: ErrorMessages;
   /**
-   * Configuration options for the useForm hook.
+   * List of required fields (by name) that must be filled before submitting the form.
+   * @default []
+   *
+   * @example
+   * requiredFields: ['name', 'email']
    */
-  export type Config = {
-    /**
-     * Custom error messages
-     *
-     * @example
-     * errorMessages: {
-     *  empty: 'Oops the form is empty!',
-     *  required: fields => `You missed: ${fields.join(', ')}`,
-     * }
-     */
-    errorMessages?: ErrorMessages;
-    /**
-     * List of required fields (by name) that must be filled before submitting the form.
-     * @default []
-     *
-     * @example
-     * requiredFields: ['name', 'email']
-     */
-    requiredFields?: string[];
+  requiredFields?: string[];
+};
+
+export type DeepRequired<T> = T extends (...args: any[]) => any
+  ? T
+  : T extends object
+    ? {
+        [K in keyof T]-?: DeepRequired<T[K]>;
+      }
+    : T;
+
+export type CaptchaRef = {
+  current: {
+    getValue: () => string;
   };
+};
+
+export type FormValues = Record<string, FormDataEntryValue | FormDataEntryValue[]>;
 
-  export type DeepRequired<T> = Required<{
-    [K in keyof T]: T[K] extends Required<T[K]> ? T[K] : DeepRequired<T[K]>;
-  }>;
-  
-  export type CaptchaRef = { current: { getValue: () => any } };
-