autoforma 1.0.62 → 1.0.64

package/README.md

@@ -1,35 +1,32 @@
-# 🚀 AutoForma
+# 🚀 Introduction
 
-**AutoForma** is a powerful and flexible **dynamic form builder** for React. It allows developers to build complex forms from simple schema definitions without writing repetitive boilerplate code. With AutoForma, you can focus on the logic and behavior of your forms — not the UI details.
+**AutoForma** is a modern, dynamic, and extensible **form builder for React** — built on top of [Mantine](https://mantine.dev/) and fully written in TypeScript.  
+It allows you to create powerful forms **entirely from JSON schema definitions**, removing repetitive boilerplate code and giving you full control over field behavior and layout.
 
----
-
-## ✨ Features
+With AutoForma, you can:
+- 🧩 Define forms using schema objects — no manual wiring.
+- 🪄 Dynamically show, hide, or disable fields based on other values.
+- 🎨 Customize the UI with your own field renderers.
+- 🧠 Extend with new field types or layouts effortlessly.
 
-- ⚡ **Fast form building:** Generate forms instantly from JSON schema.
-- 🧩 **Rich field types:** Text, Select, Checkbox, Date, Time, Switch, Tags, Array, Object, and more.
-- 🎨 **Full UI control:** Customize how each field looks and behaves.
-- 🔄 **Dynamic behavior:** Show/hide fields, enable/disable them, or update their properties based on form values.
-- 🪄 **Custom renderers:** Replace any field’s renderer with your own component.
-- 🧠 **Validation support:** Built-in and custom validation supported out of the box.
-- 📐 **Multiple layouts:** Vertical, horizontal, or grid layouts.
-- 🧪 **Extendable:** Easily integrate with any backend and add your own field types.
+> 💡 AutoForma is perfect for dashboards, admin panels, and SaaS apps where flexibility and maintainability matter.
 
 ---
 
 ## 📦 Installation
 
-Install AutoForma **and the exact peer dependencies** required for it to work properly:
+Install **AutoForma** along with its required Mantine and React peer dependencies:
 
 ```bash
-npm install autoforma @mantine/core@^7.17.5 @mantine/hooks@^7.17.5 @mantine/form@^7.17.5 @mantine/dates@^7.17.5 @mantine/tiptap@^7.17.5 @tiptap/react@^3.6.6 react@^18.0.0 react-dom@^18.0.0
+npm install autoforma   @mantine/core@^8.3.2   @mantine/hooks@^8.3.2   @mantine/form@^8.3.2   @mantine/dates@^8.3.2   @mantine/tiptap@^8.3.2   @tiptap/react@^3.6.6   react@^19.0.0   react-dom@^19.0.0
 ```
 
 ---
 
-## ⚙️ Requirements
+## ⚙️ Setup Requirements
 
-Before using `AutoForma`, make sure to wrap your application with `MantineProvider` and import Mantine's base styles:
+Before using `AutoForma`, wrap your app with the `MantineProvider`  
+and import Mantine’s global styles and optional TipTap editor styles:
 
 ```tsx
 import { MantineProvider } from "@mantine/core";
@@ -44,243 +41,171 @@ const Root = () => (
 );
 ```
 
-> ✅ Without `MantineProvider`, the components might not render or style correctly.
+> ⚠️ Without wrapping your app in `MantineProvider`,  
+> the components may not render or style correctly.
 
 ---
 
-## 🛠️ Usage
+# 🧩 Basic Usage
 
-Here's a complete example showing how to use **AutoForma** with a custom field type (`newText`):
+Here’s a quick example of how you can generate a complete form instantly using **AutoForma**.  
+Just define your schema and pass it to the `AutoForm` component — it handles layout, validation, and submission automatically.
 
 ```tsx
-import { MantineProvider } from "@mantine/core";
-import "@mantine/core/styles.css";
-import "@mantine/dates/styles.css";
-import "@mantine/tiptap/styles.css";
-import ReactDOM from "react-dom/client";
 import AutoForm from "autoforma";
-import { FieldSchema } from "autoforma";
-
-interface DemoFormValues {
-  fullName: string;
-  email: string;
-  age: number;
-  subscribe: boolean;
-  birthDate: string | null;
-  appointment: string | null;
-  contacts: { type: string; value: string }[];
-  gender: string;
-  bio: string;
-}
-
-const schema: FieldSchema[] = [
-  {
-    name: "fullName",
-    label: "Full Name",
-    type: "newText",
-    placeholder: "Enter your full name",
-    required: true,
-  },
-  {
-    name: "age",
-    label: "Age",
-    type: "number",
-    placeholder: "Enter your age",
-  },
-  {
-    name: "gender",
-    label: "Gender",
-    type: "select",
-    placeholder: "Select your gender",
-    data: [
-      { label: "Male", value: "M" },
-      { label: "Female", value: "F" },
-      { label: "Prefer not to say", value: "N" },
-    ],
-  },
-  {
-    name: "subscribe",
-    label: "Subscribe to newsletter",
-    type: "checkbox",
-    description: "Receive updates by email",
-  },
-  {
-    name: "birthDate",
-    label: "Birth Date",
-    type: "date",
-    placeholder: "Pick your birth date",
-  },
-  {
-    name: "appointment",
-    label: "Appointment",
-    type: "datetime",
-    placeholder: "Select date and time",
-  },
-  {
-    name: "contacts",
-    label: "Contacts",
-    type: "array",
-    fields: [
-      {
-        name: "type",
-        label: "Contact Type",
-        type: "select",
-        data: [
-          { label: "Email", value: "email" },
-          { label: "Phone", value: "phone" },
-        ],
-      },
-      {
-        name: "value",
-        label: "Contact Value",
-        type: "text",
-      },
-    ],
-  },
-  {
-    name: "bio",
-    label: "Bio",
-    type: "text",
-    placeholder: "Tell us about yourself",
-  },
-];
-
-const App = () => {
-  return (
-    <AutoForm<DemoFormValues>
-      layout="grid"
-      schema={schema}
-      customFieldTypes={{
-        newText: (field, form) => (
-          <div>
-            <label htmlFor={field.name}>{field.label}</label>
-            <input {...form.getInputProps(field.name)} />
-          </div>
-        ),
-      }}
-      onSubmit={(values) => alert(JSON.stringify(values))}
-    />
-  );
-};
+import { userFormSchema } from "./schema";
 
-ReactDOM.createRoot(document.getElementById("root")!).render(
-  <MantineProvider>
-    <App />
-  </MantineProvider>
+const App = () => (
+  <AutoForm
+    schema={userFormSchema}
+    onSubmit={(values) => console.log("Submitted:", values)}
+  />
 );
 ```
 
----
-
-## 🔧 Props / API Reference
-
-| Prop                    | Type                                         | Description                                               |
-| ----------------------- | -------------------------------------------- | --------------------------------------------------------- |
-| `schema`                | `FieldSchema[]`                              | The form schema definition.                               |
-| `values`                | `TValues`                                    | Initial form values.                                      |
-| `onSubmit`              | `(values: TValues) => void`                  | Callback triggered when the form is submitted.            |
-| `transformBeforeSubmit` | `(values: TValues) => TValues`               | Optional function to transform form values before submit. |
-| `transformAfterSubmit`  | `(values: TValues) => void \| Promise<void>` | Optional function called after form submission.           |
-| `validate`              | `FormValidateInput<TValues>`                 | Validation configuration.                                 |
-| `readOnly`              | `boolean`                                    | Makes the entire form read-only.                          |
-| `onFieldChange`         | `OnFieldChangeMap<TValues>`                  | Trigger callbacks when specific fields change.            |
-| `layout`                | `"vertical" \| "horizontal" \| "grid"`       | Form layout type.                                         |
-| `customFieldRenderers`  | `CustomRenderersMap<TValues>`                | Override default field renderers.                         |
-| `customFieldTypes`      | `CustomFieldTypes<TValues>`                  | Add new field types dynamically and render them.          |
-| `updateFieldSchema`     | `UpdateFieldSchemaMap<TValues>`              | Dynamically update field definitions based on values.     |
-| `submitButton`          | `boolean \| ReactNode`                       | Show or customize the submit button.                      |
+> ✅ AutoForma automatically generates labels, validation, and layouts based on your schema.
 
 ---
 
-## 🧩 Field Types
+# 🎨 Customization & Field Types
 
-AutoForma supports a variety of field types out-of-the-box:
+AutoForma gives you full control over how your form behaves and looks.  
+You can **dynamically update field properties** (like visibility, enabled state, or placeholder)  
+and even **inject your own custom field types** using `customFieldTypes`.
 
-- `text`
-- `number`
-- `select`
-- `checkbox`
-- `date`
-- `datetime`
-- `time`
-- `object`
-- `array`
-- `switch`
-- `texteditor`
-- `tags`
+---
 
-✅ **Plus any custom type** you add through `customFieldTypes`.
+## 🧠 Supported Field Types
 
----
+Out of the box, AutoForma supports a rich set of field types:
 
-## ⚙️ Advanced Usage
+| Type | Description |
+|------|--------------|
+| `text` | Standard text input |
+| `number` | Numeric input |
+| `select` | Dropdown list |
+| `checkbox` | Boolean checkbox |
+| `date` | Date picker |
+| `datetime` | Combined date & time picker |
+| `time` | Time-only picker |
+| `object` | Nested object field (grouped sub-fields) |
+| `array` | Repeating array of fields |
+| `switch` | Toggle switch |
+| `texteditor` | Rich text editor (TipTap powered) |
+| `tags` | Multi-value tag input |
+| `TCustom` | Any custom type you define via `customFieldTypes` |
 
-You can control the behavior of fields dynamically based on form values **and** extend the form with new field types:
+You can define your own type like this:
 
 ```tsx
 <AutoForm
   schema={schema}
-  updateFieldSchema={{
-    gender: (field, values) => {
-      if (values.age && values.age < 18) {
-        return { ...field, data: [{ label: "Prefer not to say", value: "N" }] };
-      }
-      return field;
-    },
-    appointment: (field, values) => ({
-      ...field,
-      disabled: !values.birthDate,
-    }),
-  }}
   customFieldTypes={{
-    newText: (field, form) => (
-      <div>
-        <label htmlFor={field.name}>{field.label}</label>
-        <input {...form.getInputProps(field.name)} />
-      </div>
+    colorPicker: (field, form) => (
+      <input
+        type="color"
+        {...form.getInputProps(field.name)}
+      />
     ),
   }}
 />
 ```
 
-✅ This gives you full power to:
+---
 
-- Dynamically adjust schema behavior.
-- Inject custom field types without touching the library core.
+# ⚙️ API Reference
 
----
+AutoForma exposes several TypeScript interfaces and configuration objects that make it fully type-safe and flexible.  
+Below are the main types you can use to configure and extend the library.
 
-## 🧪 Development
+## 🧩 `AutoFormProps<TValues>`
 
-If you want to contribute or run AutoForma locally:
+The main props accepted by the `AutoForm` component.
 
-```bash
-git clone https://github.com/your-username/AutoForma.git
-cd AutoForma
-npm install
-npm run dev
-```
+```ts
+export type AutoFormProps<
+  TValues extends Record<string, any> = Record<string, any>
+> = CustomRenderersConfig<TValues> & {
+  schema: (FieldSchema<TValues> & Record<string, any>)[];
 
----
+  initialValues?: ValueProvider<TValues>;
+  currentValues?: ValueProvider<TValues>;
 
-## 🤝 Contributing
+  prepareValues?: (values: TValues) => TValues | Promise<TValues>;
+  onSubmit: (values: TValues) => void | Promise<void>;
+  afterSubmit?: (values: TValues) => void | Promise<void>;
 
-Contributions are welcome! 🎉  
-If you'd like to help improve AutoForma:
+  validate?: FormValidateInput<TValues>;
+  readOnly?: boolean;
 
-1. Fork the repository
-2. Create a new feature branch
-3. Commit your changes
-4. Submit a pull request 🚀
+  onFieldChange?: OnFieldChangeMap<TValues>;
 
----
+  layout?: "vertical" | "horizontal" | "grid";
 
-## 📜 License
+  updateFieldSchema?: UpdateFieldSchemaMap<TValues>;
 
-This project is licensed under the **MIT License**.
+  submitButton?: boolean | React.ReactNode;
+
+  loading?: boolean;
+};
+```
+
+### 🧠 Description of Properties
+
+| Prop | Type | Description |
+|------|------|--------------|
+| `schema` | `FieldSchema[]` | The main schema defining all form fields. |
+| `initialValues` | `ValueProvider<TValues>` | Function or object returning the **initial form values** (called once). |
+| `currentValues` | `ValueProvider<TValues>` | Function or object providing **current values** (reactively updated). |
+| `prepareValues` | `(values) => TValues \| Promise<TValues>` | Modify or sanitize values before submit. |
+| `onSubmit` | `(values) => void \| Promise<void>` | Called when the form is submitted. |
+| `afterSubmit` | `(values) => void \| Promise<void>` | Called after successful submission (for side effects). |
+| `validate` | `FormValidateInput<TValues>` | Mantine validation config or validation schema. |
+| `readOnly` | `boolean` | Makes the entire form read-only. |
+| `onFieldChange` | `OnFieldChangeMap<TValues>` | Map of field-specific change handlers. |
+| `layout` | `"vertical" \| "horizontal" \| "grid"` | Form layout type. |
+| `updateFieldSchema` | `UpdateFieldSchemaMap<TValues>` | Dynamically modify schema based on values. |
+| `submitButton` | `boolean \| ReactNode` | Whether to render or customize the submit button. |
+| `loading` | `boolean` | Display a global loading state for the form. |
 
 ---
 
-## ⭐ Support
+## 🧩 `CustomRenderersConfig<TValues>`
+
+Defines all the ways you can override the default rendering logic.
+
+```ts
+export type CustomRenderersConfig<
+  TValues extends Record<string, any> = Record<string, any>
+> = {
+  customFieldRenderers?: Record<
+    string,
+    (
+      field: FieldSchema<TValues>,
+      form: UseFormReturnType<TValues>
+    ) => React.ReactNode
+  >;
+  customTypeRenderers?: Record<
+    string,
+    (
+      field: FieldSchema<TValues>,
+      form: UseFormReturnType<TValues>
+    ) => React.ReactNode
+  >;
+  customFieldTypes?: Record<
+    string,
+    (
+      field: FieldSchema<TValues>,
+      form: UseFormReturnType<TValues>
+    ) => React.ReactNode
+  >;
+};
+```
+
+### 🧠 Description of Properties
 
-If you find AutoForma helpful, please consider giving it a ⭐ on [GitHub](https://github.com/your-username/AutoForma) — it helps the project grow!
+| Prop | Type | Description |
+|------|------|--------------|
+| `customFieldRenderers` | `Record<string, (field, form) => ReactNode>` | Override rendering for specific **field names**. |
+| `customTypeRenderers` | `Record<string, (field, form) => ReactNode>` | Override rendering for specific **field types** (like `select`, `text`, etc.). |
+| `customFieldTypes` | `Record<string, (field, form) => ReactNode>` | Register completely new **custom field types**. |

package/dist/components/AutoForm/AutoForm.d.ts

@@ -1,11 +1,11 @@
 import { AutoFormRef } from './AutoForm.types';
 export declare const AutoForm: import('react').ForwardRefExoticComponent<import('../../fields/renderer.types').CustomRenderersConfig<Record<string, any>> & {
-    schema: import('../..').FieldSchema<Record<string, any>>[];
-    values?: Partial<Record<string, any>> | undefined;
-    getInitialValues?: (() => Partial<Record<string, any>> | Promise<Partial<Record<string, any>>>) | undefined;
+    schema: (import('../..').FieldSchema<Record<string, any>> & Record<string, any>)[];
+    initialValues?: (() => Partial<Record<string, any>> | Promise<Partial<Record<string, any>>>) | undefined;
+    currentValues?: (() => Partial<Record<string, any>> | Promise<Partial<Record<string, any>>>) | undefined;
+    prepareValues?: ((values: Record<string, any>) => Record<string, any> | Promise<Record<string, any>>) | undefined;
     onSubmit: (values: Record<string, any>) => void | Promise<void>;
-    transformBeforeSubmit?: ((values: Record<string, any>) => Record<string, any> | Promise<Record<string, any>>) | undefined;
-    transformAfterSubmit?: ((values: Record<string, any>) => void | Promise<void>) | undefined;
+    afterSubmit?: ((values: Record<string, any>) => void | Promise<void>) | undefined;
     validate?: import('@mantine/form').FormValidateInput<Record<string, any>> | undefined;
     readOnly?: boolean;
     onFieldChange?: import('./AutoForm.types').OnFieldChangeMap<Record<string, any>> | undefined;

package/dist/components/AutoForm/AutoForm.types.d.ts

@@ -1,13 +1,14 @@
 import { CustomRenderersConfig } from '../../fields/renderer.types';
 import { FieldSchema } from '../../fields/types';
 import { FormValidateInput, UseFormReturnType } from '@mantine/form';
+type ValueProvider<TValues> = () => Partial<TValues> | Promise<Partial<TValues>>;
 export type AutoFormProps<TValues extends Record<string, any> = Record<string, any>> = CustomRenderersConfig<TValues> & {
-    schema: FieldSchema<TValues>[];
-    values?: Partial<TValues>;
-    getInitialValues?: () => Partial<TValues> | Promise<Partial<TValues>>;
+    schema: (FieldSchema<TValues> & Record<string, any>)[];
+    initialValues?: ValueProvider<TValues>;
+    currentValues?: ValueProvider<TValues>;
+    prepareValues?: (values: TValues) => TValues | Promise<TValues>;
     onSubmit: (values: TValues) => void | Promise<void>;
-    transformBeforeSubmit?: (values: TValues) => TValues | Promise<TValues>;
-    transformAfterSubmit?: (values: TValues) => void | Promise<void>;
+    afterSubmit?: (values: TValues) => void | Promise<void>;
     validate?: FormValidateInput<TValues>;
     readOnly?: boolean;
     onFieldChange?: OnFieldChangeMap<TValues>;
@@ -32,4 +33,6 @@ export interface AutoFormRef<TValues extends Record<string, any> = Record<string
     setFieldValue: (path: string, value: any) => void;
     isValid: () => boolean;
     isDirty: () => boolean;
+    isLoading: () => boolean;
 }
+export {};