@hitesh0009/react-native-basic-form 1.2.8 → 1.3.0

package/README.md

@@ -1,20 +1,67 @@
-# react-native-basic-form
+````md
+# 🚀 React Native Basic Form
 
-A lightweight, data-driven form renderer for React Native with fully controlled inputs and flexible styling.
+### Control your entire form using JSON — not JSX.
 
-This library helps you render simple forms using a declarative data structure, without managing internal state or enforcing opinions about validation or submission.
+Building forms in React Native usually means writing repetitive JSX, duplicating layouts, and touching UI code for every small change. As apps grow, forms become hard to maintain, hard to reuse, and hard to scale.
+
+**React Native Basic Form solves this problem by turning forms into data.**
+
+Instead of hardcoding inputs, buttons, and layouts, you describe your form using a **JSON schema**.  
+The renderer stays the same — **only the JSON changes**.
+
+---
+
+## ❌ The Problem
+
+- Forms are hardcoded with JSX
+- Layout changes require code changes
+- Reusing forms across screens is painful
+- Dynamic or server-driven forms are difficult
+- UI logic and form structure get tightly coupled
+
+As a result, forms often become one of the **least maintainable parts** of an app.
+
+---
+
+## ✅ The Solution
+
+**React Native Basic Form** lets you control **everything about a form through JSON**:
+
+- what fields exist
+- how they are laid out
+- how they behave
+- how they look
+
+Change the JSON → the form changes.  
+No JSX rewrites. No duplicated components.
+
+A **schema-driven, fully customizable form renderer for React Native**.
+
+> This library does **not** manage form state, validation, or translations.  
+> It only renders what you describe.
+
+---
+
+## 🎯 Who This Is For
+
+- Apps with many forms
+- Admin panels or dashboards
+- Server-driven or config-based UIs
+- Teams that want consistent form behavior
+- Developers who prefer data-driven UI
 
 ---
 
 ## ✨ Features
 
-* 📦 No native code (JS-only)
-* 🎛 Fully controlled inputs
-* 🧩 Data-driven rendering
-* 🎨 Flexible style overrides
-* 🧠 Unopinionated & extendable
-* ⚡ Rendered using `FlatList` for performance
-* 🧰 Pass-through props for `FlatList`, `TextInput`, `Text`, and `Image`
+- 🧩 **Schema-based rendering**
+- 📐 **Row / Column layouts**
+- 🎨 **Fully customizable styles**
+- 🧠 **No internal state** (you control values & handlers)
+- 🌍 **Language-agnostic** (i18n handled by user)
+- 🛡 **Type-safe** with TypeScript
+- 🧱 **Easily extensible** (add new field types)
 
 ---
 
@@ -22,165 +69,286 @@ This library helps you render simple forms using a declarative data structure, w
 
 ```sh
 npm install @hitesh0009/react-native-basic-form
-# or
+````
+
+or
+
+```sh
 yarn add @hitesh0009/react-native-basic-form
 ```
 
 ---
 
-## 🚀 Basic Usage
+## 🚀 Quick Start
+
+### 1️⃣ Import the `Form` component
 
 ```tsx
 import { Form } from '@hitesh0009/react-native-basic-form';
+```
 
-const data = [
-  {
-    id: '1',
-    label: 'Full Name',
-    input: {
-      value: name,
-      onChangeText: setName,
-      placeholder: 'Enter your full name',
-    },
-  },
-  {
-    id: '2',
-    label: 'Phone Number',
-    input: {
-      value: phone,
-      onChangeText: setPhone,
-      placeholder: 'Enter phone number',
-      keyboardType: 'numeric',
-    },
-  },
+---
+
+### 2️⃣ Create a schema
+
+```ts
+const formSchema = [
   {
-    id: '3',
-    button: {
-      label: 'Submit',
-      onPress: handleSubmit,
-    },
+    layout: 'column',
+    spacing: 20,
+    children: [
+      {
+        type: 'input',
+        label: 'Contact Person Name',
+        inputProps: {
+          placeholder: "Enter contact person's full name",
+          onChangeText: text => console.log(text),
+        },
+      },
+      {
+        type: 'input',
+        label: 'Phone Number',
+        inputProps: {
+          placeholder: '+91 Enter phone number',
+          keyboardType: 'phone-pad',
+        },
+      },
+      {
+        type: 'button',
+        label: 'Save',
+        buttonProps: {
+          buttonText: 'Save',
+          onPress: () => console.log('Submitted'),
+        },
+      },
+    ],
   },
 ];
+```
+
+---
+
+### 3️⃣ Render the form
 
-<Form data={data} />;
+```tsx
+<Form schema={formSchema} />
 ```
 
+That’s it.
+
 ---
 
-## 🧩 Data Structure
+## 🧠 Core Concepts
+
+### 1. Schema-Driven UI
+
+You describe **what** the UI should look like:
 
 ```ts
-import type { KeyboardType } from 'react-native';
+{
+  type: 'input',
+  label: 'Name'
+}
+```
 
-export type FormItem = {
-  id: string; // must be unique
-  label?: string;
-  input?: {
-    value: string;
-    onChangeText: (text: string) => void;
-    placeholder?: string;
-    keyboardType?: KeyboardType;
-    multiline?: boolean;
-    textAlignVertical?: 'auto' | 'top' | 'center' | 'bottom';
-  };
-  button?: {
-    label: string;
-    onPress: () => void;
-  };
-};
+The form renderer handles **how** it is rendered.
+
+---
+
+### 2. Layout Blocks
+
+Each schema block controls layout only.
+
+```ts
+{
+  layout: 'row',
+  spacing: 12,
+  children: [...]
+}
 ```
 
+Supported layouts:
+
+* `column`
+* `row`
+
 ---
 
-## 🧠 Header Support (Optional)
+### 3. Fields
 
-```tsx
-<Form
-  headerIcon={Images.user}
-  headerText="Contact Information"
-/>
+Each `child` inside a block is a **field**.
+
+Supported field types:
+
+* `input`
+* `button`
+
+---
+
+## 🧩 Field Types
+
+### 🔹 Input Field
+
+```ts
+{
+  type: 'input',
+  label: 'Age',
+  spacing: 8,
+  inputProps: {
+    placeholder: 'Enter age',
+    keyboardType: 'numeric',
+    onChangeText: text => console.log(text),
+  },
+}
 ```
 
+All standard **React Native `TextInputProps`** are supported via `inputProps`.
+
 ---
 
-## 🧰 Props Reference
+### 🔹 Button Field
 
-### Core Props
+```ts
+{
+  type: 'button',
+  label: 'Submit',
+  spacing: 12,
+  style: { backgroundColor: '#2563eb' },
+  textStyle: { fontSize: 16 },
+  buttonProps: {
+    buttonText: 'Submit',
+    onPress: () => console.log('Pressed'),
+  },
+}
+```
 
-| Prop               | Type         | Description                               |
-| ------------------ | ------------ | ----------------------------------------- |
-| `data`             | `FormItem[]` | Required form definition                  |
-| `gap_bwt_keyValue` | `number`     | Gap between label and input (default: 10) |
-| `gap_bwt_keys`     | `number`     | Gap between form rows (default: 12)       |
+All standard **`TouchableOpacity` behavior** is supported via `buttonProps`.
 
 ---
 
-### Style Props
+## 🎨 Styling & Spacing
+
+Styling is **fully user-controlled**.
+
+### Field-level props
+
+| Prop         | Description                              |
+| ------------ | ---------------------------------------- |
+| `style`      | Container style                          |
+| `textStyle`  | Button text style                        |
+| `labelStyle` | Label text style                         |
+| `spacing`    | Vertical spacing between label and field |
 
-| Prop                   | Applies To       |
-| ---------------------- | ---------------- |
-| `containerStyle`       | Root container   |
-| `headerContainerStyle` | Header wrapper   |
-| `labelStyle`           | Label text       |
-| `inputTextStyle`       | TextInput        |
-| `buttonContainerStyle` | Button container |
-| `buttonTextStyle`      | Button text      |
-| `headerIconStyle`      | Header image     |
-| `headerTextStyle`      | Header text      |
+### Block-level props
+
+| Prop      | Description          |
+| --------- | -------------------- |
+| `layout`  | `row` or `column`    |
+| `spacing` | Space between fields |
 
 ---
 
-## 🔌 Pass-through Props (Advanced)
+## 🌍 Internationalization (i18n)
 
-### `flatlistProps`
+This library is **language-agnostic**.
 
-```tsx
-<Form
-  flatlistProps={{
-    scrollEnabled: false,
-    showsVerticalScrollIndicator: false,
-    contentContainerStyle: { paddingBottom: 40 },
-  }}
-/>
+You can pass translated strings directly:
+
+```ts
+label: t('contact_name')
 ```
 
-### `textInputProps`
+No translation logic is included.
 
-```tsx
-<Form
-  textInputProps={{
-    autoCapitalize: 'none',
-    returnKeyType: 'done',
-  }}
-/>
+---
+
+## 🧱 TypeScript Support
+
+The library exposes a **strict schema contract**.
+
+### Types Overview
+
+```ts
+export type FormField = FormInput | FormButton;
+
+export type FormItem = {
+  layout?: 'row' | 'column';
+  spacing?: number;
+  children: FormField[];
+};
+
+export type FormProps = {
+  schema: FormItem[];
+};
 ```
 
+TypeScript will:
+
+* prevent invalid schemas
+* autocomplete valid props
+* catch mistakes at compile time
+
 ---
 
-## ⚠️ Important Notes
+## 🧠 Design Philosophy
+
+* ❌ No internal form state
+* ❌ No validation logic
+* ❌ No opinionated UI
+* ✅ You control values & handlers
+* ✅ Schema is the single source of truth
 
-* This library does not manage state
-* All inputs are fully controlled
-* Validation and submission logic are your responsibility
-* `id` must always be a string
-* Avoid nesting inside `ScrollView` unless scrolling is disabled via `flatlistProps`
+> **This library is a render engine, not a form framework.**
 
 ---
 
-## 🧠 Design Philosophy
+## 🔧 Extending the Form
+
+To add new field types (e.g. `text`, `checkbox`, `select`):
+
+1. Extend the schema type
+2. Add a case in the renderer
+3. Plug in your component
+
+No breaking changes required.
+
+---
 
-Forms should be declarative, flexible, and boring.
+## 🧪 What This Library Is NOT
 
-This library intentionally avoids:
+* ❌ Not a validation framework
+* ❌ Not a form state manager
+* ❌ Not a UI kit
 
-* Hidden internal state
-* Opinionated validation rules
-* Forced UX decisions
+It focuses on **rendering**, not logic.
 
-Instead, it provides:
+---
+
+## 🛣 Roadmap (Optional)
+
+* Conditional rendering
+* Repeatable field groups
+* Grid layouts
+* Validation helpers
+* Visual form builder
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome.
 
-* A predictable rendering layer
-* Maximum control over behavior and styles
-* Easy integration with your existing logic
+Please keep PRs:
 
+* simple
+* schema-driven
+* backward-compatible
+
+---
+
+## 📄 License
+
+MIT
+
+```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hitesh0009/react-native-basic-form",
-  "version": "1.2.8",
+  "version": "1.3.0",
   "description": "A lightweight, data-driven form renderer for React Native with fully controlled inputs and flexible styling.",
   "keywords": [
     "react-native",