react-form-dto 0.0.8 → 1.0.0

package/README.md

@@ -1,31 +1,43 @@
 # React Form DTO
 
-**Schema-first, DTO-driven form builder for React and Material UI (MUI v7)**
+![npm](https://img.shields.io/npm/v/react-form-dto)
+![license](https://img.shields.io/npm/l/react-form-dto)
+![typescript](https://img.shields.io/badge/TypeScript-Strict-blue)
+![mui](https://img.shields.io/badge/MUI-v7-blue)
 
-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.
+**Schema-first, DTO-driven form framework for React and Material UI (MUI v7)**
+
+React Form DTO is a **high-level form framework** for building complex, dynamic, and enterprise-scale forms using declarative JSON or TypeScript DTOs—rather than verbose, repetitive JSX.
+
+It is designed for **schema-driven UIs**, backend-configured workflows, admin panels, and internal tools where forms must be **configurable, scalable, and predictable**.
 
 ---
 
 ## Why React Form DTO?
 
-Most form libraries focus on low-level state management. React Form DTO operates at a **higher abstraction level**.
+Most form libraries solve **state management**.  
+React Form DTO solves **form architecture**.
+
+It operates at a higher abstraction level where **layout, validation, rendering, and behavior** are defined in a single schema.
 
-**Use this library when:**
+### Use this library when:
 
-- 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
+- Forms are generated from backend schemas or configuration APIs
+- UI logic must be reused across multiple applications
+- Forms are large, dynamic, or conditional
+- You need imperative control (wizards, modals, async flows)
+- Your design system is based on Material UI
 
-**Key advantages:**
+### Key Advantages
 
 - 📄 **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
+- 🎨 **Material UI v7 native** – accessibility and consistency by default
+- 🧱 **Composable structure** – Form → Section → Field
+- 🎯 **Imperative API** – programmatic control via refs
+- 🔀 **Conditional rendering** – dynamic visibility and logic
+- 🧩 **Extensible renderers** – plug in custom components
+- 🛡️ **Strong TypeScript typing** – safe, predictable APIs
+- 🚀 **Enterprise-ready** – optimized for large, config-driven forms
 
 ---
 
@@ -33,22 +45,43 @@ Most form libraries focus on low-level state management. React Form DTO operates
 
 | Feature | React Form DTO | React Hook Form | Formik |
 |------|---------------|----------------|--------|
-| Schema/DTO driven | ✅ Native | ❌ Manual | ❌ Manual |
+| 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.
+> **Note:** React Form DTO is **not a replacement** for React Hook Form.  
+> It is a **higher-level abstraction** for schema-driven UI generation.
+
+---
+
+## What This Library Is Not
+
+- ❌ A low-level form state library
+- ❌ A visual form builder
+- ❌ A replacement for small hand-crafted forms
+- ❌ A design system
+
+React Form DTO excels when **forms are data, not components**.
+
+---
+
+## 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)
 
 ---
 
 ## Installation
 
 ```bash
-git clone https://github.com/Shakir-Afridi/react-form-dto.git
-cd react-form-dto
-npm install
+npm install react-form-dto
+# or
+yarn add react-form-dto
+# or
+pnpm add react-form-dto
 ```
 
 ### Requirements
@@ -59,7 +92,25 @@ npm install
 
 ---
 
-## Minimal Example
+## Core Concepts
+
+### DTO as Source of Truth
+
+All structure, layout, validation, and behavior live in a single schema.
+
+### Stateless Rendering
+
+The UI is derived entirely from the DTO and internal state.
+
+### Imperative Escape Hatch
+
+Refs enable workflows that declarative-only approaches struggle with.
+
+### Renderer Isolation
+
+Field logic is decoupled from presentation, enabling customization.
+
+## Quick Start
 
 ```tsx
 import { FormBuilder, type FormBuilderHandle } from 'react-form-dto';
@@ -201,12 +252,14 @@ const profileForm: FormDTO = {
 - `date`
 - `email`
 - `password`
+- `textarea`
 
 ### Selection Inputs
 
 - `select`
 - `autocomplete`
 - `multi-autocomplete`
+- `radio`
 
 ### Boolean Inputs
 
@@ -214,6 +267,143 @@ const profileForm: FormDTO = {
 
 ---
 
+## 🌍 Internationalization (I18n)
+
+React Form DTO has built-in support for multi-language forms through `I18String` and `I18nOption` types.
+
+### Using I18String
+
+Any text property (`label`, `placeholder`, `title`, `description`, validation messages) can be either a plain string or a locale map:
+
+```tsx
+// Simple string (single language)
+{
+  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
+```
+
+### I18n Validation Messages
+
+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:
@@ -258,14 +448,23 @@ validations: {
 
 ---
 
-## Documentation & Demo
+## Real-World Enterprise Usage
 
-- 📘 **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)
+```text
+Backend → returns FormDTO
+Frontend → renders form dynamically
+Backend updates → UI changes without redeploy
+```
+
+This enables:
+
+- Backend-driven workflows
+- Feature flags via schemas
+- Faster iteration without frontend releases
 
 ---
 
-## Ideal Use Cases
+## Other Use Cases
 
 - Admin dashboards
 - Internal enterprise tools
@@ -275,6 +474,23 @@ validations: {
 
 ---
 
+## Performance Characteristics
+
+- Independent field rendering
+- Section-level isolation
+- Optimized for 100+ field forms
+- No unnecessary re-renders across sections
+
+---
+
+## Incremental Adoption Strategy
+
+- Use React Form DTO for large dynamic forms
+- Keep React Hook Form for small custom forms
+- Share validation logic between both
+
+---
+
 ## Roadmap (Suggested)
 
 - Field registry API (`registerFieldType`)
@@ -286,11 +502,18 @@ validations: {
 
 ## 🤝 Contributing
 
-- Fork the repo
-- Create a feature branch (`git checkout -b feature/my-feature`)
-- Commit changes (`git commit -m "Add my feature"`)
-- Push to branch (`git push origin feature/my-feature`)
-- Open a Pull Request
+Contributions are welcome and encouraged.
+
+1. Fork the repository
+2. Create a feature branch
+   `git checkout -b feature/my-feature`
+3. Commit your changes
+   `git commit -m "Add my feature"`
+4. Push to the branch
+   `git push origin feature/my-feature`
+5. Open a Pull Request
+
+Please keep changes focused and well-documented.
 
 ---
 
@@ -300,4 +523,4 @@ MIT
 
 ---
 
-**React Form DTO — Schema-first forms for Material UI**
+**React Form DTO — Schema-first forms for Material UI**

package/dist/components/Field.d.ts

@@ -11,6 +11,7 @@ export interface FieldRendererProps {
     /** Callback function to update the field value */
     onChange: (val: any) => void;
     error?: string | null;
+    locale: string;
 }
 /**
  * Props for the Field component.

package/dist/components/FormBuilder.d.ts

@@ -23,6 +23,8 @@ type FormBuilderProps = {
     dto: FormDTO;
     /** Optional custom renderers for specific field types */
     renderers?: Record<string, React.ComponentType<any>>;
+    /** Current locale for i18n string resolution (default: 'en') */
+    locale?: string;
 };
 /**
  * FormBuilder component that dynamically renders a form based on a FormDTO definition.

package/dist/components/Section.d.ts

@@ -13,6 +13,8 @@ type SectionProps = {
     /** Optional custom renderers for specific field types */
     renderers?: Record<string, React.ComponentType<any>>;
     validateField: (id: string) => string[];
+    /** Current locale for i18n string resolution (default: 'en') */
+    locale?: string;
 };
 /**
  * Section component that renders a form section with its heading, description, and fields.

package/dist/components/renderers/AutoComplete.d.ts

@@ -5,6 +5,7 @@ type AutoCompleteFieldProps = {
     value: any;
     onChange: (val: any) => void;
     error?: string | null;
+    locale?: string;
 };
 export declare const AutoCompleteField: React.FC<AutoCompleteFieldProps>;
 export {};

package/dist/components/renderers/CheckBoxInput.d.ts

@@ -13,4 +13,4 @@ import { FieldRendererProps } from '../../components/Field';
  *   onChange={handleChange}
  * />
  */
-export declare function CheckBoxInput({ field, value, onChange, error, }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;
+export declare function CheckBoxInput({ field, value, onChange, error, locale, }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/renderers/MultiAutoComplete.d.ts

@@ -5,6 +5,7 @@ type MultiAutoCompleteFieldProps = {
     value: any[];
     onChange: (val: any) => void;
     error?: string | null;
+    locale?: string;
 };
 export declare const MultiAutoCompleteField: React.FC<MultiAutoCompleteFieldProps>;
 export {};

package/dist/components/renderers/RadioInput.d.ts

@@ -5,6 +5,7 @@ type RadioInputProps = {
     value: any;
     onChange: (val: any) => void;
     error?: string | null;
+    locale?: string;
 };
 export declare const RadioInput: React.FC<RadioInputProps>;
 export {};

package/dist/components/renderers/SelectInput.d.ts

@@ -13,4 +13,4 @@ import { FieldRendererProps } from '../../components/Field';
  *   onChange={handleChange}
  * />
  */
-export declare function SelectInput({ field, value, onChange, error, }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;
+export declare function SelectInput({ field, value, onChange, error, locale, }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/renderers/TextInput.d.ts

@@ -13,4 +13,4 @@ import { FieldRendererProps } from '../../components/Field';
  *   onChange={handleChange}
  * />
  */
-export declare function TextInput({ field, value, onChange, error, }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;
+export declare function TextInput({ field, value, onChange, error, locale, }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/renderers/TextareaInput.d.ts

@@ -5,6 +5,7 @@ type TextAreaInputProps = {
     value: any;
     onChange: (val: any) => void;
     error?: string | null;
+    locale?: string;
 };
 export declare const TextAreaInput: React.FC<TextAreaInputProps>;
 export {};

package/dist/examples/profileForm.d.ts

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

package/dist/hooks/useFormBuilder.d.ts

@@ -12,7 +12,7 @@ type Errors = Record<string, string | null>;
  * form.handleChange('email', 'user@example.com');
  * const errors = form.validateAll();
  */
-export declare function useFormBuilder(dto: FormDTO): {
+export declare function useFormBuilder(dto: FormDTO, locale?: string): {
     /** Current form values for all fields */
     values: Record<string, any>;
     /** Function to update a field value */