finform-react-builder 1.5.5 → 1.5.7

package/README.md

@@ -208,6 +208,214 @@ export default App;
 ```
 
 ### Checkbox Fields
+### Autocomplete (Single)
+```tsx
+{
+  name: 'country',
+  label: 'Country',
+  type: 'autocomplete',
+  placeholder: 'Search country',
+  options: [
+    { label: 'United States', value: 'us' },
+    { label: 'Canada', value: 'ca' },
+  ],
+  // For API-driven:
+  // api_endpoint: '/common/countries?format=dropdown',
+  // api_method: 'GET',
+  // value_field: 'id',
+  // label_field: 'label',
+}
+```
+
+### Autocomplete (Multiple) with Checkboxes and +N More Chips
+```tsx
+{
+  name: 'skills',
+  label: 'Skills',
+  type: 'autocomplete',
+  multiple: true,
+  options: [
+    { label: 'JavaScript', value: 'javascript' },
+    { label: 'React', value: 'react' },
+    { label: 'TypeScript', value: 'typescript' },
+  ],
+  // Stored value is an array of primitive values: ['javascript', 'react']
+}
+```
+Behavior:
+- Renders checkboxes in the dropdown when `multiple: true`.
+- Only the first 2 selections are rendered as chips; if more, shows a `+N more` chip.
+- Works with API-driven data using `api_endpoint`, `value_field`, `label_field`.
+
+### Toggle (Segmented Radios)
+```tsx
+{
+  name: 'gender',
+  label: 'Gender',
+  type: 'toggle',
+  options: [
+    { label: 'Male', value: 'male' },
+    { label: 'Female', value: 'female' },
+    { label: 'Other', value: 'other' },
+  ],
+  required: true,
+}
+```
+
+### Radio (Vertical)
+```tsx
+{
+  name: 'contactPreference',
+  label: 'Contact Preference',
+  type: 'radio',
+  options: [
+    { label: 'Email', value: 'email' },
+    { label: 'Phone', value: 'phone' },
+  ],
+}
+```
+
+### Switch
+```tsx
+{
+  name: 'notifications',
+  label: 'Enable Notifications',
+  type: 'switch',
+}
+```
+
+### Title and Section Headings
+```tsx
+{ name: 'formTitle', type: 'title', label: 'Create User', variant: 'h4', col: 12 }
+{ name: 'detailsSection', type: 'section', label: 'Details', variant: 'h6', col: 12 }
+```
+
+## 🔗 API-Driven Fields and Dependencies
+
+### Basic API-Driven Select
+```tsx
+{
+  name: 'country_id',
+  label: 'Country',
+  type: 'select',
+  api_endpoint: '/common/countries?format=dropdown',
+  api_method: 'GET',
+  value_field: 'id',
+  label_field: 'label',
+}
+```
+
+### Dependent Field (Conditional + depends_on)
+```tsx
+{
+  name: 'org_type_id',
+  label: 'Entity Type',
+  type: 'autocomplete',
+  api_endpoint: '/company/org-types/active/list',
+  api_method: 'GET',
+  value_field: 'id',
+  label_field: 'name',
+},
+{
+  name: 'parent_id',
+  label: 'Parent Entity',
+  type: 'autocomplete',
+  api_endpoint: '/company/offices/potential-parents/{org_type_id}?format=dropdown',
+  api_method: 'GET',
+  depends_on: 'org_type_id',
+  conditional: true,
+  value_field: 'id',
+  label_field: 'label',
+}
+```
+Behavior:
+- The dependent field (`parent_id`) is disabled until `org_type_id` has a value.
+- When the dependency value changes, the dependent field is reset (clears previous selection).
+
+## ✅ Validation and Submit Button Behavior
+
+- Required fields must be filled; for arrays (e.g., multi-select), value must be non-empty.
+- Required checkboxes must be true.
+- Any validation error (including on non-required fields) disables submit.
+- Single-step forms: built-in Submit button is disabled until valid.
+- Multi-step forms: Next/Submit are disabled until the current step is valid.
+
+Number validation example (number type):
+```tsx
+{
+  name: 'longitude',
+  label: 'Longitude',
+  type: 'number',
+  validation: { min: -180, max: 180, message: 'Longitude must be between -180 and 180' },
+}
+```
+For `type: 'text'` number-like validation, use `pattern` or `custom` in `validation`.
+
+## 🧭 Buttons and Button Groups
+
+### Custom Buttons
+```tsx
+<FinForm
+  fields={fields}
+  buttons={[
+    { text: 'Cancel', type: 'button', onClick: () => navigate(-1) },
+    { text: 'Submit', type: 'submit', color: 'primary' },
+  ]}
+/>
+```
+- Submit (and Next) buttons are auto-disabled when the form (or current step) is invalid.
+- Non-submit buttons (e.g., Cancel) remain clickable.
+
+### Button Group
+```tsx
+<FinForm
+  fields={fields}
+  buttonGroup={{
+    position: 'right',
+    buttons: [
+      { text: 'Previous', type: 'button' },
+      { text: 'Next', type: 'button' },
+      { text: 'Submit', type: 'submit' },
+    ],
+  }}
+/>
+```
+- Buttons with text containing "Next", "Submit", "Save", "Finish", "Complete" are treated as flow actions and auto-disabled appropriately.
+
+## 🎨 Theming
+```tsx
+<FinForm
+  theme={{
+    primaryColor: '#2196f3',
+    secondaryColor: '#f50057',
+    backgroundColor: '#fafafa',
+    textColor: '#333',
+    borderRadius: 8,
+    spacing: 16,
+    typography: { fontFamily: 'Roboto, Arial, sans-serif', fontSize: 16 },
+  }}
+  fields={fields}
+  onSubmit={...}
+/>
+```
+
+## 🖼️ Image Field
+```tsx
+{
+  name: 'profileImage',
+  label: 'Profile Image',
+  type: 'image',
+  defaultValue: 'https://via.placeholder.com/300x200',
+  alt: 'User profile image',
+  width: 300,
+  height: 200,
+  onClick: () => console.log('Image clicked')
+}
+```
+
+## 🔁 onChange
+`onChange` is fired with current form values on every change, without creating render loops, and accounts for dependent resets.
+
 ```tsx
 {
   name: 'newsletter',