react-form-dto 0.0.5 → 0.0.7

package/README.md

@@ -1,41 +1,49 @@
 # React Form DTO
 
-A **dynamic, DTO-driven form builder** built with **React, TypeScript, and Material UI (MUI v7)**.  
-This library lets you define forms declaratively using JSON DTOs (`FormDTO`, `SectionDTO`, `FieldDTO`) and automatically renders responsive, accessible forms with MUI components.
+**Schema-first, DTO-driven form builder for React and Material UI (MUI v7)**
+
+React Form DTO helps you build complex, responsive, and accessible forms using declarative JSON/TypeScript DTOs instead of verbose JSX. It is designed for enterprise-grade applications, internal tools, admin panels, and workflows where forms are dynamic, configurable, and data-driven.
 
 ---
 
-## ✨ Features
+## Why React Form DTO?
 
-- **DTO-driven**: Define forms entirely in JSON/TypeScript objects.
-- **Material UI integration**: Uses MUI v7 components for consistent design and accessibility.
-- **Responsive grid layout**: 12-column system mapped to MUI’s `Grid` with `size` props.
-- **Conditional rendering**: Show/hide fields or sections based on other field values.
-- **Custom renderers**: Override default MUI inputs with your own components.
-- **TypeScript support**: Strongly typed DTOs for safety and autocompletion.
-- **Composable architecture**: `FormBuilder`, `Section`, and `Field` components.
-- **Built-in validation**: Use `useFormBuilder` hook and validation utilities for field and form validation.
+Most form libraries focus on low-level state management. React Form DTO operates at a **higher abstraction level**.
 
----
+**Use this library when:**
 
-📘 Documentation
+- Your forms are generated from backend schemas or configurations
+- You want to avoid duplicating UI logic across applications
+- You need imperative control over form state (wizards, modals, async flows)
+- Your project is built on Material UI
 
-Comprehensive documentation is available here
+**Key advantages:**
 
-👉 [Documentation](https://shakir-afridi.github.io/react-form-dto/docs)
+- 📄 **DTO-first design** – define forms entirely in JSON or TypeScript
+- 🎨 **Material UI v7 native** – consistent design & accessibility
+- 🧱 **Composable architecture** – Form → Section → Field
+- 🎯 **Imperative API** – programmatic access via refs
+- 🔀 **Conditional rendering** – show/hide fields dynamically
+- 🧩 **Custom renderers** – plug in your own components
+- 🛡️ **Strong TypeScript typing** – predictable, safe APIs
 
 ---
 
-## 📘 Storybook
+## How It Compares
 
-Explore it interactively on Storybook:  
-👉 [Live Demo](https://shakir-afridi.github.io/react-form-dto/storybook)
+| Feature | React Form DTO | React Hook Form | Formik |
+|------|---------------|----------------|--------|
+| Schema/DTO driven | ✅ Native | ❌ Manual | ❌ Manual |
+| MUI-first | ✅ Yes | ⚠️ Partial | ⚠️ Partial |
+| Imperative API | ✅ First-class | ⚠️ Limited | ⚠️ Limited |
+| Large dynamic forms | ✅ Excellent | ⚠️ Medium | ❌ Poor |
+| Boilerplate | ✅ Minimal | ❌ High | ❌ High |
 
----
+> React Form DTO is **not a replacement** for React Hook Form. It is a higher-level abstraction for schema-driven UI generation.
 
-## 📦 Installation
+---
 
-Clone the repo and install dependencies:
+## Installation
 
 ```bash
 git clone https://github.com/Shakir-Afridi/react-form-dto.git
@@ -43,16 +51,15 @@ cd react-form-dto
 npm install
 ```
 
-> **Requirements:**  
-> - Node.js >= 18  
-> - React >= 19  
-> - Material UI >= 7
+### Requirements
 
----
+- Node.js >= 18
+- React >= 19
+- Material UI >= 7
 
-## 🏗️ Usage
+---
 
-Import and use the form builder in your React app:
+## Minimal Example
 
 ```tsx
 import { FormBuilder, type FormBuilderHandle } from 'react-form-dto';
@@ -79,11 +86,9 @@ return (
 );
 ```
 
-Refer to the documentation and examples for DTO structure and customization.
-
 ---
 
-### 📋 Example
+## 📋 Example Form rendered
 
 ![Form Example](./example.png)
 
@@ -187,28 +192,187 @@ const profileForm: FormDTO = {
 
 ---
 
-### Supported Field Types & Renderers
+## Supported Field Types
+
+### Text Inputs
+
+- `text`
+- `number`
+- `date`
+- `email`
+- `password`
+
+### Selection Inputs
 
-- **TextInput**: text, number, date
-- **SelectInput**: select/dropdown
-- **CheckBoxInput**: boolean/checkbox
-- **AutoCompleteField**: single autocomplete
-- **MultiAutoCompleteField**: multi-select autocomplete
+- `select`
+- `autocomplete`
+- `multi-autocomplete`
 
-You can provide a custom renderer for any field via the DTO:
+### Boolean Inputs
+
+- `checkbox`
+
+---
+
+## 🌍 Internationalization (I18n)
+
+React Form DTO has built-in support for multi-language forms through `I18nText` and `I18nOption` types.
+
+### Using I18nText
+
+Any text property (`label`, `placeholder`, `title`, `description`, validation messages) can be either a plain string or a locale map:
 
 ```tsx
+// Simple string (single language)
 {
-  // ...existing field DTO...
-  renderer: MyCustomComponent
+  label: "First Name"
 }
+
+// Multi-language support
+{
+  label: {
+    en: "First Name",
+    fr: "Prénom",
+    es: "Nombre",
+    de: "Vorname"
+  }
+}
+```
+
+### Using I18nOption for Selections
+
+For select, autocomplete, and multi-autocomplete fields, you can use `I18nOption` objects to provide translatable labels while maintaining stable values:
+
+```tsx
+{
+  id: "country",
+  type: "select",
+  label: { en: "Country", fr: "Pays" },
+  options: [
+    {
+      value: "us",
+      label: { en: "United States", fr: "États-Unis" }
+    },
+    {
+      value: "fr",
+      label: { en: "France", fr: "France" }
+    },
+    {
+      value: "de",
+      label: { en: "Germany", fr: "Allemagne" }
+    }
+  ]
+}
+```
+
+**Backward Compatibility:** Simple string arrays still work:
+
+```tsx
+options: ["USA", "France", "Germany"] // Still supported
 ```
 
-### Validation
+### I18n Validation Messages
 
-The `useFormBuilder` hook provides the following API for managing form state and validation:
+Validation messages also support I18n:
 
 ```tsx
+validations: {
+  required: {
+    en: "This field is required",
+    fr: "Ce champ est obligatoire",
+    es: "Este campo es obligatorio"
+  },
+  validate: (value) => value.length < 2 
+    ? { 
+        en: "Minimum 2 characters",
+        fr: "Minimum 2 caractères" 
+      }
+    : null
+}
+```
+
+### Complete I18n Example
+
+```tsx
+const multilingualForm: FormDTO = {
+  title: {
+    en: "User Registration",
+    fr: "Inscription de l'utilisateur",
+    es: "Registro de Usuario"
+  },
+  description: {
+    en: "Please fill in your details",
+    fr: "Veuillez remplir vos coordonnées",
+    es: "Por favor complete sus datos"
+  },
+  sections: [
+    {
+      id: "personal",
+      heading: {
+        en: "Personal Information",
+        fr: "Informations personnelles",
+        es: "Información Personal"
+      },
+      fields: [
+        {
+          id: "title",
+          type: "select",
+          label: { en: "Title", fr: "Titre", es: "Título" },
+          options: [
+            { value: "mr", label: { en: "Mr", fr: "M.", es: "Sr." } },
+            { value: "ms", label: { en: "Ms", fr: "Mme", es: "Sra." } },
+            { value: "dr", label: { en: "Dr", fr: "Dr", es: "Dr." } }
+          ]
+        },
+        {
+          id: "firstName",
+          type: "text",
+          label: { en: "First Name", fr: "Prénom", es: "Nombre" },
+          placeholder: { 
+            en: "Enter your first name",
+            fr: "Entrez votre prénom",
+            es: "Ingrese su nombre"
+          },
+          validations: {
+            required: {
+              en: "First name is required",
+              fr: "Le prénom est obligatoire",
+              es: "El nombre es obligatorio"
+            }
+          }
+        }
+      ]
+    }
+  ]
+};
+```
+
+> **Note:** The library provides the I18n structure. You'll need to implement locale selection and text resolution in your application layer.
+
+---
+
+## Custom Field Renderers
+
+Override any default renderer by supplying your own component:
+
+```ts
+{
+  id: "salary",
+  type: "number",
+  label: "Salary",
+  renderer: CurrencyInput
+}
+```
+
+This makes the library extensible without modifying core logic.
+
+---
+
+## Validation API
+
+Validation is handled through the `useFormBuilder` hook and the imperative form handle.
+
+```ts
 const {
   handleChange,   // Function to update a field value: (id, value) => void
   validateAll,    // Function to validate all fields: () => Record<string, string[]>
@@ -218,13 +382,42 @@ const {
 } = useFormBuilder(myFormDTO);
 ```
 
-- `handleChange(id, value)`: Update a field value.
-- `validateAll()`: Validate all fields and return errors.
-- `validateField(id)`: Validate a specific field and return errors for that field.
-- `getValues()`: Get all form values.
-- `getErrors()`: Get all form errors.
+### Validation Rules
 
-Refer to the documentation and examples for DTO structure and customization.
+```ts
+validations: {
+  required: "This field is required",
+  validate: (value) => value.length < 2 ? "Minimum 2 characters" : null
+}
+```
+
+> Recommendation: Standardize validation return values to `string[]` for predictable handling in large applications.
+
+---
+
+## Documentation & Demo
+
+- 📘 **Documentation:** See full DTO reference, APIs, and advanced examples [Documentation](https://shakir-afridi.github.io/react-form-dto/docs)
+- 📗 **Storybook:** Interactive component playground and live demos [Live Demo](https://shakir-afridi.github.io/react-form-dto/storybook)
+
+---
+
+## Ideal Use Cases
+
+- Admin dashboards
+- Internal enterprise tools
+- Multi-step onboarding flows
+- Config-driven forms from APIs
+- Rapid UI scaffolding for MUI projects
+
+---
+
+## Roadmap (Suggested)
+
+- Field registry API (`registerFieldType`)
+- Async validation support
+- Form-level conditional logic
+- Schema import (JSON Schema / OpenAPI)
 
 ---
 
@@ -240,4 +433,8 @@ Refer to the documentation and examples for DTO structure and customization.
 
 ## 📜 License
 
-MIT License © 2025 Shakir Ullah
+MIT
+
+---
+
+**React Form DTO — Schema-first forms for Material UI**

package/dist/examples/profileForm.i18n.d.ts

@@ -0,0 +1,2 @@
+import { FormDTO } from '../types';
+export declare const profileFormI18n: FormDTO;

package/dist/types/dto.d.ts

@@ -5,13 +5,18 @@ export type LayoutDTO = {
     align?: "start" | "center" | "end" | "stretch";
     justify?: "start" | "center" | "end" | "space-between";
 };
+export type I18nText = string | Record<string, string>;
+export type I18nOption = {
+    value: string;
+    label: I18nText;
+};
 export type InputType = "text" | "email" | "password" | "textarea" | "number" | "select" | "checkbox" | "date" | "autocomplete" | "multi-autocomplete" | "radio";
 export type FieldDTO = {
     id: string;
     type: InputType;
-    label: string;
-    placeholder?: string;
-    options?: string[];
+    label: I18nText;
+    placeholder?: I18nText;
+    options?: Array<I18nOption | I18nText>;
     rows?: number;
     disabled?: boolean;
     defaultValue?: any;
@@ -20,27 +25,27 @@ export type FieldDTO = {
 };
 export type SectionDTO = {
     id: string;
-    heading?: string;
+    heading?: I18nText;
     headingFontSize?: number;
-    description?: string;
+    description?: I18nText;
     descriptionFontSize?: number;
     layout?: LayoutDTO;
     fields: FieldDTO[];
 };
 export type FormDTO = {
-    title?: string;
+    title?: I18nText;
     titleFontSize?: number;
-    description?: string;
+    description?: I18nText;
     descriptionFontSize?: number;
     layout?: LayoutDTO;
     sections: SectionDTO[];
 };
 export type Validations = {
-    required?: boolean | string;
+    required?: boolean | I18nText;
     min?: number;
     max?: number;
     minLength?: number;
     maxLength?: number;
     pattern?: RegExp;
-    validate?: (value: any) => string | null;
+    validate?: (value: any) => I18nText | null;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "react-form-dto",
     "description": "A React library for building forms using DTOs with MUI and TypeScript.",
-    "version": "0.0.5",
+    "version": "0.0.7",
     "main": "dist/react-form-dto.umd.js",
     "module": "dist/react-form-dto.es.js",
     "types": "dist/index.d.ts",