formaze 1.0.3 → 1.0.5

package/README.md

@@ -19,7 +19,7 @@ npm install formaze
 ```tsx
 // if you are using next.js (app router) then activate the below line "use client" directive otherwise remove it
 
-// "use client" 
+// "use client"
 import { z } from "zod";
 import { useFormSchema, createFormValidator } from "formaze";
 /* for pre-styled css (check the styling guide below) */
@@ -53,11 +53,13 @@ export function RegistrationForm() {
 	return (
 		<Form schema={formSchema} onSubmit={handleSubmit}>
 			<Form.Input
-			 	type="email" 
-				name="email" 
+				label="Email"
+				type="email"
+				name="email"
 				placeholder="Enter your email"
 			/>
 			<Form.Input
+				label="Password"
 				type="password"
 				name="password"
 				placeholder="Enter your password"
@@ -116,7 +118,7 @@ import { z } from "zod";
 
 const formSchema = z.object({
 	email: z.string().email(),
-	name: z.string().min(3, {message: "Required"})
+	name: z.string().min(3, { message: "Required" }),
 });
 ```
 
@@ -133,7 +135,7 @@ You can specify the following validation options for each field:
 
 ## Styling
 
-- For Tailwind (pre-styled)
+-  For Tailwind (pre-styled)
 
 Follow the [Official Tailwind Docs](https://tailwindcss.com/docs/installation/framework-guides) for initializing project with vite or next.js
 
@@ -143,43 +145,44 @@ You can add your own styles or import the below css (styled with tailwind css) f
 import "formaze/dist/style.css";
 ```
 
-- For Pure CSS
-Here are the css classes with default styles, add it into main css file
+-  For Pure CSS
+   Here are the css classes with default styles, add it into main css file
+
 ```css
 .form-control {
-   display: flex;
-   flex-direction: column;
-   justify-content: center;
-   gap: 1rem;
+	display: flex;
+	flex-direction: column;
+	justify-content: center;
+	gap: 1rem;
 }
 
 .form-control .form-field {
-   display: flex;
-   flex-direction: column;
-   justify-content: center;
+	display: flex;
+	flex-direction: column;
+	justify-content: center;
 }
 
 .form-control .form-field .form-input {
-   padding: 10px 1rem;
-   border-radius: 10px;
-   border-width: 1px;
-   border-color: rgb(209 213 219);
+	padding: 10px 1rem;
+	border-radius: 10px;
+	border-width: 1px;
+	border-color: rgb(209 213 219);
 }
 
 .form-control .form-field .form-input:focus {
-   border-color: rgb(59 130 246);
-   outline: none;
+	border-color: rgb(59 130 246);
+	outline: none;
 }
 
-.form-control .form-field-error-text { 
-   color: rgb(220, 38, 38);
+.form-control .form-field-error-text {
+	color: rgb(220, 38, 38);
 	font-size: 0.875rem;
 }
 
 /* or */
 
-.form-control .form-field-error { 
-   color: rgb(220, 38, 38);
+.form-control .form-field-error {
+	color: rgb(220, 38, 38);
 }
 ```
 
@@ -188,8 +191,147 @@ Here are the css classes with default styles, add it into main css file
 You just have to add `"use client"` directive at the top of your file where you are using this form and its related methods
 
 ```tsx
-"use client"
+"use client";
 // your code
 ```
 
+## Components and Hooks
+
+### `createFormValidator`
+
+The createFormValidator function returns a Form component with built-in form validation using Zod and React Hook Form. It simplifies the creation of forms that adhere to a Zod schema for type-safe validation.
+
+**Returned Form Component Props**:
+
+**schema: `T`**
+
+-  Type: `T` (A Zod schema)
+
+-  Description:
+   The schema prop is a schema used to define the structure and validation rules for the form. This schema determines the expected fields, their types, and any validation logic, such as required fields, minimum/maximum values, regex patterns, etc.
+
+-  Example:
+
+```tsx
+const schema = useFormSchema({
+	email: { type: "email" },
+	password: { type: "string", minLength: { value: 8 } },
+});
+
+const Form = createFormValidator<typeof schema>();
+
+<Form schema={schema} onSubmit={handleSubmit} />;
+```
+
+**onSubmit: `SubmitHandler<z.infer<T>>`**
+
+-  Type: `SubmitHandler<z.infer<T>>`
+
+-  Description:
+   The onSubmit prop accepts a function that is called when the form is successfully submitted. The function receives the form's validated data as its argument, which is inferred from the useFormSchema (using Zod) schema (z.infer<T>).
+
+-  Example:
+
+```tsx
+const schema = useFormSchema({
+	email: { type: "email" },
+	password: { type: "string" },
+});
+
+const onSubmit = (data: z.infer<typeof schema>) => {
+	console.log(data); // { email: "test@example.com", password: "securePassword" }
+};
+
+<Form schema={schema} onSubmit={onSubmit} />;
+```
+
+**defaultValues?: `DefaultValues<z.infer<T>>`**
+
+-  Type: `DefaultValues<z.infer<T>>`
+
+-  Description:
+   This optional prop allows you to specify default values for the form fields. The keys should exactly match the fields defined in the useFormSchema/Zod schema, and the values should be of the appropriate type.
+
+-  Example:
+
+```tsx
+const schema = useFormSchema({
+	email: { type: "email" },
+	password: { type: "string" },
+});
+
+const defaultValues = {
+	email: "example@example.com",
+	password: "",
+};
+
+<Form schema={schema} defaultValues={defaultValues} onSubmit={onSubmit} />;
+```
+
+**children: React.ReactNode**
+
+-  Type: `React.ReactNode`
+
+-  Description:
+   The children prop accepts form inputs and other JSX elements to be rendered inside the Form component. It specifically expects components like Form.Input, which is designed to integrate with the form's validation logic. The Form.Input component handles binding form fields to the Zod schema, ensuring that validation rules are properly applied.
+
+You can include Form.Input for each form field, along with any other elements like buttons or additional form elements. The Form.Input automatically manages validation states based on the schema.
+
+-  Example:
+
+```tsx
+<Form schema={schema} onSubmit={onSubmit} defaultValues={defaultValues}>
+	<Form.Input name="email" placeholder="Email" />
+	<Form.Input type="password" name="password" placeholder="Password" />
+	<button type="submit">Submit</button>
+</Form>
+```
+
+**Input component of the generated Form**
+
+**Form.Input**
+
+The Form.Input component is a form input field that is connected to a Zod-based form schema. It ensures that the field is validated according to the rules defined in the schema.
+
+**Props:**
+
+- name: `keyof z.infer<T>`
+The name of the form field, which should correspond to one of the keys in the Zod schema used in the form. This connects the input to the form's validation logic.
+
+- label: `string` (optional)
+A label for the form field. This is used for displaying a descriptive text for the input field.
+
+- ...props: `React.HTMLAttributes<HTMLInputElement>`
+Any additional props that can be passed to an HTML input element. These props allow you to customize the input field, such as adding a placeholder, className, type, etc.
+
+### `useFormSchema`
+
+useFormSchema is a utility function that generates a Zod schema based on the provided configuration. It supports various field types such as string, email, password, number, date, and boolean, along with validation rules like minLength, maxLength, regex, etc.
+
+#### Arguments
+
+**schemaConfig: `SchemaConfig<T>`**
+
+-  Type: `SchemaConfig<T>`
+
+-  Description:
+   The schemaConfig defines the fields and validation rules for the schema. Each field in the config should specify its type (string, email, password, etc.), whether it is optional, and any additional validation logic, such as minLength, maxLength, or regex.
+
+-  Example:
+
+```tsx
+const schema = useFormSchema({
+	email: { type: "email" },
+	password: {
+		type: "string",
+		minLength: {
+			value: 8,
+			message: "Password must be at least 8 characters long",
+		},
+	},
+});
+```
+
+This schema can then be passed to the Form component returned by `createFormValidator`.
+
 ## (That's it!)

package/dist/index.d.ts

@@ -10,7 +10,7 @@ interface FormProps<T extends z.ZodSchema>
 }
 
 interface InputProps<T extends z.ZodSchema>
-	extends React.InputHTMLAttributes<HTMLInputElement> {
+	extends React.HTMLAttributes<HTMLInputElement> {
 	name: keyof z.infer<T>;
 	label?: string;
 }
@@ -98,11 +98,73 @@ type SchemaKeyValuePair<T extends SchemaConfig<Record<string, FieldConfig>>> = {
 		: z.ZodTypeAny;
 };
 
+/**
+ * Generates a Form component with built-in validation using Zod and React Hook Form.
+ * The returned Form component also includes an Input component for form fields with automatic schema-based validation.
+ *
+ * @template T - The Zod schema used to define the structure and validation rules for the form.
+ *
+ * @returns {{
+ *   ({schema, children, className, onSubmit, ...props}: FormProps<T>): JSX.Element;
+ *   Input: ({label, name, className, ...props}: InputProps<T>) => JSX.Element;
+ * }} - The generated Form component that supports schema-based form handling and an Input component for each form field.
+ *
+ * @component Form
+ * @param {T} schema - Zod schema defining the form fields and validation rules.
+ * @param {SubmitHandler<z.infer<T>>} onSubmit - Function to handle form submission after successful validation.
+ * @param {DefaultValues<z.infer<T>>} [defaultValues] - Optional default values to pre-populate the form fields.
+ * @param {React.ReactNode} children - Form fields and other JSX components, including Form.Input components.
+ * @param {string} [className] - Optional class for the form element.
+ *
+ * @component Input
+ * @param {keyof z.infer<T>} name - The name of the form field, matching the key of the schema.
+ * @param {string} label - Label for the form input.
+ * @param {string} [className] - Optional class for the input element.
+ * @param {...any} props - Additional input attributes like `type`, `placeholder`, etc.
+ *
+ * @example
+ * // Create a Zod schema
+ * const schema = useFormSchema({
+ *   email: { type: "email" },
+ *   password: { type: "string", minLength: { value: 8 } },
+ * });
+ *
+ * // Use the generated Form component
+ * const MyForm = createFormValidator<typeof schema>();
+ *
+ * <MyForm schema={schema} onSubmit={handleSubmit}>
+ *   <MyForm.Input name="email" label="Email" />
+ *   <MyForm.Input name="password" label="Password" type="password" />
+ *   <button type="submit">Submit</button>
+ * </MyForm>;
+ */
+
 declare const createFormValidator: <T extends z.ZodSchema>() => {
 	({ schema, onSubmit, children, className }: FormProps<T>): JSX.Element;
 	Input({ name, label, className, ...props }: InputProps<T>): JSX.Element;
 };
 
+/**
+ * Generates a Zod schema based on the provided configuration.
+ * This utility function is useful for creating dynamic form schemas with validation rules.
+ *
+ * @template T - The shape of the schema config, where T extends a record of field configurations.
+ *
+ * @param {SchemaConfig<T>} schemaConfig - An object that defines the fields and validation rules for the form.
+ * Each key in the object represents a form field, and its value specifies the field's type, optional status, and any additional validation logic.
+ *
+ * @returns {z.ZodObject<T>} - Returns a Zod schema that can be used for form validation.
+ *
+ * @example
+ * const schema = useFormSchema({
+ *   email: { type: "email" },
+ *   password: {
+ *     type: "string",
+ *     minLength: { value: 8 },
+ *   },
+ * });
+ */
+
 declare const useFormSchema: <
 	T extends SchemaConfig<Record<string, FieldConfig>>
 >(

package/package.json

@@ -3,7 +3,7 @@
 	"description": "An easy form validation package for react, built by using React hook form and zod library",
 	"main": "dist/formaze.js",
 	"types": "dist/index.d.ts",
-	"version": "1.0.3",
+	"version": "1.0.5",
 	"type": "module",
 	"keywords": [
 		"react",
@@ -14,7 +14,7 @@
 	],
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/Its-Samir/formaze"
+		"url": "git+https://github.com/Its-Samir/formaze.git"
 	},
 	"license": "MIT",
 	"scripts": {