react-smart-fields 1.1.5 → 2.1.0

package/README.md

@@ -1,191 +1,279 @@
-# 🧹 DynamicFields React Component
+# React Smart Fields
 
 ![npm](https://img.shields.io/npm/v/react-smart-fields)
 ![downloads](https://img.shields.io/npm/dw/react-smart-fields)
 ![license](https://img.shields.io/npm/l/react-smart-fields)
-![issues](https://img.shields.io/github/issues/Pratikpanchal25/react-smart-fields)
 
+`react-smart-fields` is a powerful dynamic form renderer for React with:
 
-A flexible, fully-styled dynamic form generator built with **React** and **Tailwind CSS**, supporting custom input types, validation, and class overrides. Ideal for building forms quickly with full control over design and behavior.
+- configurable field schemas
+- built-in + custom validation
+- conditional visibility/disable/required rules
+- async options for selects
+- nested field names (`user.addresses[0].city`)
+- theme presets + headless mode + full render slots
 
----
+## Installation
 
-## ✨ Features
-
-* 📦 Supports `text`, `number`, `checkbox`, `radio`, and `select` fields
-* 💅 Fully customizable via Tailwind-compatible className props
-* 🧠 Built-in required field validation
-* 🧱 Extensible for advanced usage
-* 🌃 Full **dark mode** support
-* 🔄 Real-time `onChange` callback with live `formData` and `errors`
-
----
-
-## 📦 Installation
-
-Copy the `DynamicFields.tsx` file into your React project.
-
-Make sure you have Tailwind CSS and React configured in your app.
+```bash
+npm install react-smart-fields
+```
 
----
+or
 
-## 🚀 Usage
+```bash
+yarn add react-smart-fields
+```
 
-### Basic Example
+## Quick Start
 
 ```tsx
-import React from "react";
-import DynamicFields from "./DynamicFields";
+import { DynamicFields, FieldConfig } from "react-smart-fields";
 
-const fields = [
-  {
-    name: "username",
-    label: "Username",
-    type: "text",
-    required: true,
-  },
+const fields: FieldConfig[] = [
+  { name: "name", label: "Name", type: "text", required: true },
   {
     name: "email",
     label: "Email",
-    type: "text",
-    required: true,
-  },
-  {
-    name: "gender",
-    label: "Gender",
-    type: "radio",
+    type: "email",
     required: true,
-    options: [
-      { label: "Male", value: "male" },
-      { label: "Female", value: "female" },
-    ],
+    pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+    patternMessage: "Please enter a valid email",
   },
   {
     name: "country",
     label: "Country",
     type: "select",
+    placeholder: "Select country",
     options: [
-      { label: "USA", value: "us" },
       { label: "India", value: "in" },
+      { label: "United States", value: "us" },
     ],
   },
   {
-    name: "subscribe",
-    label: "Subscribe",
+    name: "newsletter",
+    label: "Subscribe to newsletter",
     type: "checkbox",
-  }
+    defaultValue: true,
+  },
 ];
 
-function App() {
-  const handleChange = (data) => {
-    console.log("Form Data:", data);
-  };
-
+export default function App() {
   return (
     <DynamicFields
       fields={fields}
-      title="Sign Up"
-      description="Please fill all fields"
-      onChange={handleChange}
+      title="Profile"
+      description="Update your profile details"
+      theme="default"
+      size="md"
+      onChange={(values, meta) => {
+        console.log(values, meta?.errors);
+      }}
     />
   );
 }
 ```
 
----
-
-## ⚙️ Props
+## Major Capabilities
+
+- **Validation engine**: `required`, `min/max`, `minLength/maxLength`, `pattern`, and `validate`
+- **Conditional behavior**: `showWhen`, `disableWhen`, `requiredWhen`
+- **Nested paths**: dot/bracket field names are supported
+- **Async select options**: `loadOptions` with `loadOptionsOn: "mount" | "change"`
+- **Theme presets**: `default`, `minimal`, `filled`, `underline`
+- **Headless mode**: set `headless` to fully control UI
+- **Render slots**: `renderField`, `renderControl`, `renderLabel`, `renderDescription`, `renderError`
+- **State styling hooks**: `stateClassNames` for `invalid`, `disabled`, `readonly`, `dirty`, `touched`
+
+## Component Props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `fields` | `FieldConfig[]` | ✅ | Field schema array |
+| `onChange` | `(values, meta?) => void` | ✅ | Fires on every value/meta update |
+| `value` | `Record<string, any>` | ❌ | Controlled mode values |
+| `defaultValues` | `Record<string, any>` | ❌ | Initial values (uncontrolled mode) |
+| `resolver` | `(values) => errors \| Promise<errors>` | ❌ | External validation resolver |
+| `validateMode` | `"change" \| "blur"` | ❌ | Validation trigger mode |
+| `showErrorWhen` | `"always" \| "touched" \| "dirty"` | ❌ | Error visibility strategy |
+| `headless` | `boolean` | ❌ | Disables built-in styling |
+| `theme` | `"default" \| "minimal" \| "filled" \| "underline"` | ❌ | Built-in visual preset |
+| `size` | `"sm" \| "md" \| "lg"` | ❌ | Input/label sizing |
+| `ui` | `UiClassMap` | ❌ | Global slot class overrides |
+| `stateClassNames` | `StateClassNames` | ❌ | State class hooks |
+| `renderField` | `(ctx) => ReactNode` | ❌ | Full custom field renderer |
+| `renderControl` | `(ctx) => ReactNode` | ❌ | Custom control renderer |
+| `renderLabel` | `(ctx) => ReactNode` | ❌ | Custom label renderer |
+| `renderDescription` | `(ctx) => ReactNode` | ❌ | Custom helper text renderer |
+| `renderError` | `(ctx) => ReactNode` | ❌ | Custom error renderer |
+| `title` | `string` | ❌ | Form heading |
+| `description` | `string` | ❌ | Form subtitle |
+
+Legacy class props are still supported for backward compatibility:
+`className`, `inputClassName`, `labelClassName`, `mainFieldClassName`, `fieldClassName`, `errorClassName`, `selectClassName`, `optionClassName`, `checkboxClassName`, `radioClassName`.
+
+## FieldConfig API
 
-| Prop                 | Type                                  | Required | Description                       |
-| -------------------- | ------------------------------------- | -------- | --------------------------------- |
-| `fields`             | `FieldConfig[]`                       | ✅ Yes    | List of field definitions         |
-| `onChange`           | `(data: Record<string, any>) => void` | ✅ Yes    | Callback on value change          |
-| `title`              | `string`                              | ❌ No     | Optional form title               |
-| `description`        | `string`                              | ❌ No     | Optional description              |
-| `className`          | `string`                              | ❌ No     | Wrapper div styling               |
-| `mainFieldClassName` | `string`                              | ❌ No     | Class for the fields wrapper      |
-| `inputClassName`     | `string`                              | ❌ No     | Applies to `text`/`number` inputs |
-| `labelClassName`     | `string`                              | ❌ No     | Applies to all labels             |
-| `fieldClassName`     | `string`                              | ❌ No     | Applied to each field wrapper div |
-| `errorClassName`     | `string`                              | ❌ No     | Error message styling             |
-| `selectClassName`    | `string`                              | ❌ No     | `select` field styling            |
-| `checkboxClassName`  | `string`                              | ❌ No     | Checkbox input styling            |
-| `radioClassName`     | `string`                              | ❌ No     | Radio input styling               |
-| `optionClassName`    | `string`                              | ❌ No     | Dropdown option styling           |
-
----
-
-## 🔧 `FieldConfig` (field definition)
+```ts
+type FieldConfig = {
+  name: string;
+  label?: string;
+  type:
+    | "text"
+    | "number"
+    | "select"
+    | "radio"
+    | "checkbox"
+    | "textarea"
+    | "email"
+    | "password"
+    | "tel"
+    | "url"
+    | "date";
+
+  // values/options
+  defaultValue?: any;
+  placeholder?: string;
+  options?: { label: string; value: string | number | boolean | null | undefined; disabled?: boolean }[];
+  loadOptions?: (ctx: { values: Record<string, any>; field: FieldConfig }) => Promise<FieldOption[]>;
+  loadOptionsOn?: "mount" | "change";
+
+  // behavior
+  disabled?: boolean;
+  readOnly?: boolean;
+  showWhen?: (values: Record<string, any>) => boolean;
+  disableWhen?: (values: Record<string, any>) => boolean;
+  required?: boolean;
+  requiredWhen?: (values: Record<string, any>) => boolean;
+  requiredMessage?: string;
+
+  // validation
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: RegExp;
+  patternMessage?: string;
+  validate?: (value: any, values: Record<string, any>) => string | undefined | null;
+
+  // value transforms
+  transformIn?: (storedValue: any, values: Record<string, any>) => any;
+  transformOut?: (rawValue: any, values: Record<string, any>) => any;
+
+  // styling/rendering
+  className?: string;
+  inputClassName?: string;
+  labelClassName?: string;
+  errorClassName?: string;
+  ui?: UiClassMap;
+  renderControl?: (ctx: RenderControlContext) => ReactNode;
+};
+```
 
-Each field object can contain:
+## Customization Examples
 
-| Property      | Type                                                      | Required                          | Notes                                  |
-| ------------- | --------------------------------------------------------- | --------------------------------- | -------------------------------------- |
-| `name`        | `string`                                                  | ✅ Yes                             | Unique key                             |
-| `label`       | `string`                                                  | ❌ No                              | Display label                          |
-| `type`        | `"text"`, `"number"`, `"select"`, `"radio"`, `"checkbox"` | ✅ Yes                             | Field type                             |
-| `required`    | `boolean`                                                 | ❌ No                              | Show red asterisk and basic validation |
-| `placeholder` | `string`                                                  | ❌ No                              | Placeholder (for inputs/selects)       |
-| `description` | `string`                                                  | ❌ No                              | Optional helper text                   |
-| `options`     | `{ label: string; value: any; }[]`                        | Required for `select` and `radio` | Dropdown/Radio values                  |
+### 1) Conditional + Nested Fields
 
----
+```tsx
+const fields: FieldConfig[] = [
+  { name: "accountType", label: "Account Type", type: "select", options: [
+    { label: "Individual", value: "individual" },
+    { label: "Business", value: "business" },
+  ]},
+  {
+    name: "company.name",
+    label: "Company Name",
+    type: "text",
+    showWhen: (values) => values.accountType === "business",
+    requiredWhen: (values) => values.accountType === "business",
+  },
+  {
+    name: "addresses[0].city",
+    label: "Primary City",
+    type: "text",
+    required: true,
+  },
+];
+```
 
-## 🎨 Class Mapping
+### 2) Async Select Options
 
-Here's how classes are applied to each section:
+```tsx
+{
+  name: "state",
+  label: "State",
+  type: "select",
+  loadOptionsOn: "change",
+  loadOptions: async ({ values }) => {
+    if (!values.country) return [];
+    const response = await fetch(`/api/states?country=${values.country}`);
+    const data = await response.json();
+    return data.map((item: any) => ({ label: item.name, value: item.code }));
+  },
+}
+```
 
-| Section             | Class Prop          | Default Tailwind Example           |
-| ------------------- | ------------------- | ---------------------------------- |
-| Wrapper div         | `className`         | `bg-white dark:bg-gray-900`        |
-| Label text          | `labelClassName`    | `text-gray-800 dark:text-gray-200` |
-| Input fields        | `inputClassName`    | `bg-white dark:bg-gray-800`        |
-| Select dropdown     | `selectClassName`   | `rounded-lg`                       |
-| Radio buttons       | `radioClassName`    | `rounded-full`                     |
-| Checkbox            | `checkboxClassName` | `rounded`                          |
-| Field container div | `fieldClassName`    | `w-full`                           |
-| Dropdown options    | `optionClassName`   | `hover:bg-gray-100`                |
-| Error messages      | `errorClassName`    | `text-red-500`                     |
+### 3) Headless + Slots
 
-You can override all styles with your own Tailwind classes!
+```tsx
+<DynamicFields
+  fields={fields}
+  headless
+  renderField={({ field, labelNode, controlNode, errorNode, helpNode }) => (
+    <div key={field.name} className="mb-6">
+      {labelNode}
+      <div className="mt-2">{controlNode}</div>
+      <div className="mt-1">{helpNode}</div>
+      <div className="mt-1">{errorNode}</div>
+    </div>
+  )}
+  onChange={(values) => console.log(values)}
+/>
+```
 
----
+### 4) Resolver Validation
 
-## 🧪 Advanced Usage: Custom Styling Per Field
+```tsx
+<DynamicFields
+  fields={fields}
+  resolver={(values) => {
+    const errors: Record<string, string> = {};
+    if (values.password !== values.confirmPassword) {
+      errors.confirmPassword = "Passwords do not match";
+    }
+    return errors;
+  }}
+  onChange={(values, meta) => {
+    console.log(meta?.errors);
+  }}
+/>
+```
 
-You can add `inputClassName`, `labelClassName`, or `className` inside each field:
+## Type Exports
 
 ```ts
-{
-  name: "email",
-  label: "Email",
-  type: "text",
-  inputClassName: "border-purple-500",
-  labelClassName: "text-purple-700 font-semibold",
-  className: "mb-6",
-}
+import type {
+  FieldConfig,
+  FieldOption,
+  FieldType,
+  DynamicFieldsProps,
+  UiClassMap,
+  StateClassNames,
+  ChangeMeta,
+  RenderControlContext,
+  RenderFieldContext,
+} from "react-smart-fields";
 ```
 
----
+## Author
 
-## 🧑‍💻 Author
-
-**Name:** Pratik Panchal
+**Name:** Pratik Panchal  
 **GitHub:** [@Pratikpanchal25](https://github.com/Pratikpanchal25)
 
----
-
-
-## 📄 License
+## License
 
 MIT — Free to use, modify and distribute.
 
----
-
-## 🛠 Contributing
-
-Pull requests are welcome! If you find bugs, feel free to [open an issue](https://github.com/ShubhamNakum/DynamicFields/issues).
-
----
+## Contributing
 
-<!-- Keywords: react form builder, tailwind forms, dynamic form, smart form, react tailwind input -->
+Pull requests are welcome! If you find bugs, feel free to open an issue.