commons-shared-web-ui 0.0.60 → 0.0.62

package/documentation/smart-form.md

@@ -0,0 +1,2819 @@
+# Smart Form Module
+
+A powerful, JSON-driven dynamic form builder for Angular applications. This module allows you to create complex forms with conditional visibility, auto-calculated fields, multi-section support, stepper navigation, repeatable groups, column-based layouts, automatic API submission, and full i18n support — using simple JSON configurations.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Form Types](#form-types)
+- [Field Types](#field-types)
+- [Layout System](#layout-system)
+- [Configuration Options](#configuration-options)
+- [Advanced Features](#advanced-features)
+- [i18n / Translation Support](#i18n--translation-support)
+- [API Submission](#api-submission)
+- [API Authentication (Token)](#api-authentication-token)
+- [Theme Configuration](#theme-configuration)
+- [Examples](#examples)
+- [API Reference](#api-reference)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Installation
+
+To install the latest version of the `commons-shared-web-ui` library, run the following command:
+
+```bash
+npm install commons-shared-web-ui@latest
+```
+
+1. Import the module in your Angular application:
+
+```typescript
+import { SmartFormModule } from "./modules/smart-form/smart-form.module";
+
+@NgModule({
+  imports: [SmartFormModule],
+})
+export class AppModule {}
+```
+
+---
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { Component } from "@angular/core";
+
+@Component({
+  selector: "app-example",
+  template: `
+    <lib-smart-form
+      [formJson]="formJson"
+      [initialValues]="initialValues"
+      [labels]="labels"
+      (submit)="onSubmit($event)"
+    >
+    </lib-smart-form>
+  `,
+})
+export class ExampleComponent {
+  formJson = JSON.stringify({
+    entityType: "USER",
+    label: "FORM.TITLE",
+    formType: "SECTION",
+    sectionConfig: {
+      children: [
+        {
+          name: "firstName",
+          label: "FIELD.FIRST_NAME",
+          type: "TEXT_INPUT",
+          subType: "SHORT",
+          required: true,
+        },
+        {
+          name: "email",
+          label: "FIELD.EMAIL",
+          type: "TEXT_INPUT",
+          subType: "EMAIL",
+          required: true,
+        },
+      ],
+    },
+  });
+
+  initialValues = { firstName: "John" };
+
+  labels = {
+    "FORM.TITLE": "User Registration",
+    "FIELD.FIRST_NAME": "First Name",
+    "FIELD.EMAIL": "Email Address",
+  };
+
+  onSubmit(data: any) {
+    console.log("Form submitted:", data);
+  }
+}
+```
+
+---
+
+## Form Types
+
+### 1. Section Form (SECTION)
+
+A simple form with all fields displayed at once.
+
+```json
+{
+  "entityType": "USER",
+  "label": "User Form",
+  "formType": "SECTION",
+  "sectionConfig": {
+    "children": [...]
+  }
+}
+```
+
+### 2. Stepper Form (STEPPER)
+
+A multi-step form with navigation between steps. Each step is a `GROUP` field with a `sectionConfig`.
+
+```json
+{
+  "entityType": "USER",
+  "label": "User Registration",
+  "formType": "STEPPER",
+  "stepperConfig": {
+    "children": [
+      {
+        "type": "GROUP",
+        "subType": "SECTION",
+        "sectionConfig": {
+          "label": "Step 1: Basic Info",
+          "children": [...]
+        }
+      },
+      {
+        "type": "GROUP",
+        "subType": "SECTION",
+        "sectionConfig": {
+          "label": "Step 2: Contact Info",
+          "children": [...]
+        }
+      }
+    ],
+    "showStep": true,
+    "isHorizontal": true
+  }
+}
+```
+
+### 3. Section Stepper (SECTION + `sectionStepper`)
+
+A `SECTION` form where top-level `GROUP` children are rendered as a horizontal step-progress bar at the top, showing one section at a time. Set `"sectionStepper": true` to enable it explicitly. The form auto-detects it when all top-level children are `GROUP` type — set `"sectionStepper": false` to suppress auto-detection.
+
+> **Note:** A schema with exactly **one** surviving top-level `GROUP` (e.g. after a business user disables every other section via the Field Selection Configurator — see `form-builder.md`) is still treated as a section stepper. The step nav bar itself is hidden when there's only one step, so it renders as a plain single-section form instead of the blank result older versions produced in this case.
+
+The component automatically renders **Previous** and **Next** buttons in the action bar. Any configured `actionBarConfig` buttons appear alongside these navigation buttons.
+
+```json
+{
+  "entityType": "REGISTRATION",
+  "label": "Multi-Step Registration",
+  "formType": "SECTION",
+  "sectionStepper": true,
+  "sectionConfig": {
+    "children": [
+      {
+        "type": "GROUP",
+        "subType": "SECTION",
+        "sectionConfig": {
+          "label": "Personal Info",
+          "children": [...]
+        }
+      },
+      {
+        "type": "GROUP",
+        "subType": "SECTION",
+        "sectionConfig": {
+          "label": "Contact Details",
+          "children": [...]
+        }
+      },
+      {
+        "type": "GROUP",
+        "subType": "SECTION",
+        "sectionConfig": {
+          "label": "Review & Submit",
+          "children": [...]
+        }
+      }
+    ]
+  }
+}
+```
+
+| Setting | Behaviour |
+|---------|-----------|
+| `"sectionStepper": true` | Always enables section stepper |
+| `"sectionStepper": false` | Disables section stepper; renders all sections at once in the regular layout |
+| Omitted | Auto-detected when all top-level children are `GROUP` type (one or more) |
+
+### Host-Driven Navigation (Section Stepper `@ViewChild` API)
+
+For layouts where the host app renders its **own** Previous/Next/Submit buttons (instead of relying on `actionBarConfig`), grab a reference to `SmartFormComponent` via `@ViewChild` and drive the stepper directly:
+
+```typescript
+import { ViewChild } from '@angular/core';
+import { SmartFormComponent } from 'commons-shared-web-ui';
+
+export class MyWizardComponent {
+  @ViewChild(SmartFormComponent) smartFormComponent!: SmartFormComponent;
+
+  onStepChange(info: { currentStep: number; totalSteps: number; isFirst: boolean; isLast: boolean; stepLabel: string }) {
+    this.stepInfo = info; // drive your own footer UI from this
+  }
+
+  onNextClicked(): void {
+    // isCurrentStepValid() marks the current step's controls as touched and returns
+    // false if any required field on THIS step is invalid — navigateToNext() itself
+    // never blocks, it always advances (it only records a soft "warning" badge state).
+    if (this.smartFormComponent.isCurrentStepValid() === false) {
+      return; // field-level error states are now visible; stop here
+    }
+    this.smartFormComponent.navigateToNext();
+  }
+}
+```
+
+```html
+<lib-smart-form
+  [formJson]="formJson"
+  (stepChange)="onStepChange($event)">
+</lib-smart-form>
+```
+
+| Member | Type | Description |
+| :--- | :--- | :--- |
+| `navigateToNext()` | method | Advances to the next section step. Marks the step being left with a `valid`/`warning` badge but **always advances** regardless of validity. |
+| `navigateToPrevious()` | method | Goes back to the previous section step. Does not run validation. |
+| `goToSectionStep(index)` | method | Jumps directly to a step by index (e.g. clicking a step nav bubble). Validates the step being left, same as `navigateToNext()`. |
+| `isCurrentStepValid()` | method → `boolean` | **The hard-block guard.** Marks every control in the current step as touched (so field-level errors render) and returns `false` if any required field is invalid. Call this before `navigateToNext()` if your screen must prevent skipping incomplete steps — `navigateToNext()` alone will never do this for you. Returns `true` immediately for non-stepper forms. |
+| `isSectionStepFirst` | getter → `boolean` | `true` when on the first step. |
+| `isSectionStepLast` | getter → `boolean` | `true` when on the last step. For a single-step form (see note above), this and `isSectionStepFirst` are both `true` simultaneously. |
+| `(stepChange)` | `EventEmitter<{ currentStep, totalSteps, isFirst, isLast, stepLabel }>` | Emitted after every step change — use it to sync a custom footer/progress UI. |
+
+> **Important:** validation is opt-in at the host level. If you never call `isCurrentStepValid()`, users can freely skip past incomplete required fields by clicking Next — only the step's nav badge shows a warning. This is intentional: some hosts want a soft warning only, others (e.g. multi-step onboarding wizards) want a hard block. Add the `isCurrentStepValid()` check in your own Next handler only if you want the latter.
+
+---
+
+## Field Types
+
+### 1. Text Input (TEXT_INPUT)
+
+**SubTypes:** `SHORT`, `LONG`, `EMAIL`, `PHONE`, `PASSWORD`
+
+```json
+{
+  "name": "firstName",
+  "label": "First Name",
+  "type": "TEXT_INPUT",
+  "subType": "SHORT",
+  "required": true,
+  "hint": "Enter your first name",
+  "placeholder": "e.g. John",
+  "textConfig": {
+    "length": { "min": 2, "max": 50 },
+    "pattern": "^[A-Za-z ]+$",
+    "patternMessage": "Only alphabets and spaces are allowed"
+  }
+}
+```
+
+**Password with match validation** (`subType: PASSWORD` + `matchField`):
+
+```json
+{
+  "name": "password",
+  "label": "Password",
+  "type": "TEXT_INPUT",
+  "subType": "PASSWORD",
+  "required": true,
+  "textConfig": { "length": { "min": 8, "max": 64 } }
+},
+{
+  "name": "confirmPassword",
+  "label": "Confirm Password",
+  "type": "TEXT_INPUT",
+  "subType": "PASSWORD",
+  "required": true,
+  "textConfig": { "matchField": "password" }
+}
+```
+
+The `matchField` property tells the field to validate that its value equals the named sibling field. If the values differ, a `passwordMismatch` error is added and a user-friendly message is displayed.
+
+### 2. Number Input (NUMBER_INPUT)
+
+**SubTypes:** `INTEGER`, `DECIMAL`
+
+```json
+{
+  "name": "age",
+  "label": "Age",
+  "type": "NUMBER_INPUT",
+  "subType": "INTEGER",
+  "required": true,
+  "numberConfig": { "min": 18, "max": 100, "step": 1 }
+}
+```
+
+### 3. Date Input (DATE)
+
+**SubTypes:** `SINGLE`
+
+```json
+{
+  "name": "birthDate",
+  "label": "Date of Birth",
+  "type": "DATE",
+  "subType": "SINGLE",
+  "required": true,
+  "dateConfig": {
+    "allowFuture": false,
+    "minDate": "1920-01-01",
+    "maxDate": "2010-12-31"
+  }
+}
+```
+
+**`dateConfig` properties**
+
+| Property | Type | Description |
+|---|---|---|
+| `allowFuture` | `boolean` | When `false`, dates after today are blocked (default: `true`) |
+| `minDate` | `string` | Static minimum date in `YYYY-MM-DD` format |
+| `maxDate` | `string` | Static maximum date in `YYYY-MM-DD` format |
+| `minDateField` | `string` | Name of a sibling field whose current value is used as the dynamic minimum date. When the source field changes, the min date updates reactively. If the current field's value is now before the new minimum, it is automatically cleared. |
+| `inputReadonly` | `boolean` | When `true`, the text input is read-only — the user can only pick a date from the calendar, not type one. Default: `false` |
+
+**Dynamic min date (linked to another field)**
+
+Use `minDateField` to link the minimum of an end-date picker to a start-date field:
+
+```json
+[
+  {
+    "name": "startDate",
+    "label": "Start Date",
+    "type": "DATE",
+    "subType": "SINGLE",
+    "required": true,
+    "dateConfig": { "inputReadonly": true }
+  },
+  {
+    "name": "endDate",
+    "label": "End Date",
+    "type": "DATE",
+    "subType": "SINGLE",
+    "required": true,
+    "dateConfig": {
+      "inputReadonly": true,
+      "minDateField": "startDate"
+    }
+  }
+]
+```
+
+The End Date picker automatically sets its minimum to whatever value `startDate` holds. If the user later picks an earlier start date, `endDate` is cleared automatically.
+
+### 4. Time Input (TIME)
+
+**SubTypes:** `SINGLE`
+
+```json
+{
+  "name": "meetingTime",
+  "label": "Meeting Time",
+  "type": "TIME",
+  "subType": "SINGLE",
+  "required": true,
+  "placeholder": "Select Time"
+}
+```
+
+**`timeConfig` options** (all optional):
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `minTime` | string | Explicit minimum time in 24-hour `"HH:mm"` format (e.g. `"09:00"`). |
+| `maxTime` | string | Explicit maximum time in 24-hour `"HH:mm"` format (e.g. `"18:00"`). |
+| `inputReadonly` | boolean | When true, the input is readonly. |
+| `minTimeField` | string | Name of a sibling TIME field whose value is used as the dynamic minimum. When it changes, this field's minimum updates and any now-invalid value (earlier than the new minimum) is cleared. Mirrors `dateConfig.minTimeField`. |
+| `variant` | string | Rendering variant: `'default'` (native picker input, default) or `'wheel'` (custom drum-roll slide picker). |
+| `mode` | string | Hour display mode for `'wheel'` variant: `'12'` (12-hour, AM/PM column, default) or `'24'` (24-hour, no AM/PM). |
+| `minuteStep` | number | Minute column increment step for `'wheel'` variant. Omit (or `1`) for every minute `00–59`; a value greater than `0` adds the break (e.g. `5`, `10`, `15`, `30`). |
+| `placeholder` | string | Overridden placeholder text for the `'wheel'` variant trigger field. |
+
+**Start / End time pair** — the end time cannot be earlier than the start time (same pattern as `dateConfig.minDateField`):
+
+```json
+{
+  "name": "startTime",
+  "label": "Start Time",
+  "type": "TIME",
+  "required": true,
+  "colSpan": 2
+},
+{
+  "name": "endTime",
+  "label": "End Time",
+  "type": "TIME",
+  "required": true,
+  "colSpan": 2,
+  "timeConfig": {
+    "minTimeField": "startTime"
+  }
+}
+```
+
+**Custom Wheel Time Picker Example** — using the custom drum-roll picker with 12-hour mode and 15-minute increments:
+
+```json
+{
+  "name": "preferredSlot",
+  "label": "Preferred Meeting Slot",
+  "type": "TIME",
+  "subType": "SINGLE",
+  "required": true,
+  "timeConfig": {
+    "variant": "wheel",
+    "mode": "12",
+    "minuteStep": 15,
+    "minTime": "09:00",
+    "maxTime": "17:00",
+    "placeholder": "Choose a 15-minute slot"
+  }
+}
+```
+
+> **Note:** `minuteStep` omitted (or `0`/`1`) shows every minute `00–59`; any value greater than `0` adds the step break (e.g. `15` → `00, 15, 30, 45`). The wheel opens as a compact, centered modal.
+
+**Styling & Variants (SCSS)**:
+By default, the time picker uses the black/grey theme (Image 2 style). To use a blue accent variant instead, include the theme mixin with overrides inside your global stylesheet or MFE container styles:
+
+```scss
+@use 'commons-shared-web-ui/lib/modules/time-picker/time-picker.theme' as tp;
+
+// Default variant (Black/Grey Color Scheme)
+:root {
+  @include tp.time-picker-theme();
+}
+
+// Blue Accent Variant
+:root {
+  @include tp.time-picker-theme((
+    accent:              #4D89EB,
+    accent-light:        rgba(77, 137, 235, 0.08),
+    accent-border:       rgba(77, 137, 235, 0.15),
+    btn-confirm-bg:      #4D89EB,
+    btn-confirm-hover:   #3b74d1,
+    btn-cancel-bg:       transparent,
+    btn-cancel-border:   #e5e7eb,
+    btn-cancel-hover:    #e5e7eb
+  ));
+}
+```
+
+**Time Picker i18n labels** — the `'wheel'` variant reads these keys from the form-level `[labels]` map (all optional; each falls back to English):
+
+| Label key | Applies to | Default |
+| --- | --- | --- |
+| `TIME_PICKER.SELECT_TIME` | Popup title | `Select Time` |
+| `TIME_PICKER.HOUR` | Hour column header | `Hour` |
+| `TIME_PICKER.MINUTE` | Minute column header | `Minute` |
+| `TIME_PICKER.PERIOD` | AM/PM column header | `AM/PM` |
+| `TIME_PICKER.AM` / `TIME_PICKER.PM` | Period values | `AM` / `PM` |
+| `COMMON.ACTIONS.CONFIRM` | Confirm button | `Confirm` |
+| `COMMON.ACTIONS.CANCEL` | Cancel button | `Cancel` |
+
+#### Complete Example (TIME wheel field in a Smart Form)
+
+A full form schema with a start/end wheel time-picker pair, plus the parent-component wiring and picker i18n labels.
+
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-booking-form',
+  template: `
+    <lib-smart-form
+      [formJson]="formJson"
+      [labels]="labels"
+      (submit)="onSubmit($event)">
+    </lib-smart-form>
+  `
+})
+export class BookingFormComponent {
+  formJson = JSON.stringify({
+    entityType: 'BOOKING',
+    label: 'FORM.BOOKING_TITLE',
+    formType: 'SECTION',
+    sectionConfig: {
+      children: [
+        {
+          type: 'ROW',
+          subType: 'HORIZONTAL',
+          children: [
+            {
+              name: 'startTime',
+              label: 'FIELD.START_TIME',
+              type: 'TIME',
+              subType: 'SINGLE',
+              required: true,
+              colSpan: 6,
+              timeConfig: {
+                variant: 'wheel',
+                mode: '12',
+                minuteStep: 15,
+                minTime: '09:00',
+                maxTime: '18:00'
+              }
+            },
+            {
+              name: 'endTime',
+              label: 'FIELD.END_TIME',
+              type: 'TIME',
+              subType: 'SINGLE',
+              required: true,
+              colSpan: 6,
+              timeConfig: {
+                variant: 'wheel',
+                mode: '12',
+                minuteStep: 15,
+                minTimeField: 'startTime'   // end cannot precede start
+              }
+            }
+          ]
+        }
+      ]
+    },
+    submitConfig: {
+      apiUrl: 'https://api.example.com/bookings',
+      method: 'POST',
+      successMessage: 'Booking created!'
+    }
+  });
+
+  labels = {
+    'FORM.BOOKING_TITLE': 'New Booking',
+    'FIELD.START_TIME': 'Start Time',
+    'FIELD.END_TIME': 'End Time',
+    // Time picker popup i18n
+    'TIME_PICKER.SELECT_TIME': 'Pick a time',
+    'TIME_PICKER.HOUR': 'Hour',
+    'TIME_PICKER.MINUTE': 'Min',
+    'TIME_PICKER.PERIOD': 'AM/PM',
+    'COMMON.ACTIONS.CONFIRM': 'Confirm',
+    'COMMON.ACTIONS.CANCEL': 'Cancel'
+  };
+
+  onSubmit(payload: any): void {
+    // { startTime: "09:15 AM", endTime: "10:00 AM" }
+    console.log('Booking:', payload);
+  }
+}
+```
+
+### 5. Autocomplete (AUTOCOMPLETE)
+
+A searchable input backed by Angular Material's `mat-autocomplete`. As the user types, the option list is filtered by label or code. The form control stores the **code** value, while the input shows the human-readable **label**.
+
+Autocomplete fields now use a dedicated `autocompleteConfig` for specialized behavior, while still using `optionConfig` for core API/data settings.
+
+#### Basic Usage (Local Filtering)
+
+```json
+{
+  "name": "country",
+  "label": "Country",
+  "type": "AUTOCOMPLETE",
+  "subType": "SINGLE",
+  "optionConfig": {
+    "optionList": [
+      { "label": "India",  "code": "IN" },
+      { "label": "USA",    "code": "US" }
+    ]
+  }
+}
+```
+
+#### Advanced Usage (Server-side Search & Rich Display)
+
+For large datasets, use `autocompleteConfig` to trigger server-side filtering and display rich metadata (emails, phones, avatars) in the dropdown options.
+
+```json
+{
+  "name": "responsiblePerson",
+  "label": "Responsible Person",
+  "type": "AUTOCOMPLETE",
+  "optionConfig": {
+    "apiUrl": "gateway/search-service/api/v1/users",
+    "dataPath": "elements",
+    "labelPath": "displayName",
+    "valuePath": "userId"
+  },
+  "autocompleteConfig": {
+    "method": "POST",
+    "body": [],
+    "searchParam": "searchTerm",
+    "searchMinLength": 2,
+    "displayFields": [
+      { "path": "photoUrl", "type": "image" },
+      { "path": "login",    "type": "email", "label": "Email: " },
+      { "path": "phone",    "type": "phone" }
+    ]
+  }
+}
+```
+
+#### Autocomplete Configuration (`autocompleteConfig`)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `method` | `'GET' \| 'POST' \| 'PUT' \| 'PATCH'` | HTTP method for the search API (Default: `GET`). |
+| `body` | `any` | Static request body for `POST`/`PUT`/`PATCH` requests. |
+| `labelTemplate` | `string` | Template string for composite labels, e.g., `"{firstName} {lastName} ({empId})"`. |
+| `displayFields` | `string \| DisplayField[]` | Extra fields to show below the label. See [Rich Display Fields](#rich-display-fields). |
+| `searchParam` | `string` | Query parameter key sent to the API as the user types (e.g., `"q"` or `"searchTerm"`). |
+| `searchMinLength`| `number` | Minimum characters to type before firing an API request (Default: `1`). |
+| `searchDebounce` | `number` | Delay in ms before firing the search request (Default: `300ms`). |
+
+#### Rich Display Fields
+
+The `displayFields` property allows you to show extra information in the dropdown. Each field is rendered with an appropriate icon and style.
+
+| Type | Rendering |
+| :--- | :--- |
+| `text` | Plain secondary text (Default). |
+| `email` | Rendered with an envelope icon in a pill-style chip. |
+| `phone` | Rendered with a phone icon in a pill-style chip. |
+| `image` | Rendered as a small circular avatar/thumbnail. |
+
+#### Autocomplete Behaviour
+
+| Feature | Detail |
+| :--- | :--- |
+| **Debouncing** | Automatically waits for the user to stop typing before calling the API. |
+| **Syncing** | If the form is patched with a `code`, the component automatically fetches or resolves the `label` for display. |
+| **Edge Case Handling** | If a user types an invalid value and blurs, the input reverts to the last valid selection. |
+| **Clear Button** | A built-in "X" button allows users to reset the field instantly. |
+
+### 4. Dropdown (DROPDOWN)
+
+**SubTypes:** `SINGLE`, `MULTIPLE`
+
+**Static options:**
+
+```json
+{
+  "name": "country",
+  "label": "Country",
+  "type": "DROPDOWN",
+  "subType": "SINGLE",
+  "required": true,
+  "optionConfig": {
+    "optionList": [
+      { "label": "USA", "code": "US" },
+      { "label": "Canada", "code": "CA" }
+    ]
+  }
+}
+```
+
+**Load from API** (supports nested data paths):
+
+```json
+{
+  "name": "department",
+  "label": "Department",
+  "type": "DROPDOWN",
+  "subType": "SINGLE",
+  "optionConfig": {
+    "apiUrl": "https://api.example.com/departments",
+    "dataPath": "data.items",
+    "labelPath": "profile.name",
+    "valuePath": "meta.id"
+  }
+}
+```
+
+**Dependent Dropdown (Cascading Select):**
+
+```json
+{
+  "name": "state",
+  "label": "State",
+  "type": "DROPDOWN",
+  "subType": "SINGLE",
+  "optionConfig": {
+    "apiUrl": "https://api.example.com/states",
+    "valuePath": "code"
+  }
+},
+{
+  "name": "district",
+  "label": "District",
+  "type": "DROPDOWN",
+  "subType": "SINGLE",
+  "optionConfig": {
+    "apiUrl": "https://api.example.com/districts",
+    "dependencies": {
+      "stateCode": "state"
+    }
+  }
+}
+```
+
+`dependencies` maps API query-param keys to other field names. The parent field's current value is automatically appended to the API URL.
+
+**Merge Multiple APIs:**
+
+```json
+{
+  "name": "region",
+  "label": "Region",
+  "type": "DROPDOWN",
+  "subType": "SINGLE",
+  "optionConfig": {
+    "apiUrls": [
+      "https://api.example.com/states",
+      "https://api.example.com/union-territories"
+    ],
+    "valuePath": "code",
+    "labelPath": "name"
+  }
+}
+```
+
+**Sort Options:**
+
+```json
+{
+  "name": "country",
+  "label": "Select Country",
+  "type": "DROPDOWN",
+  "subType": "SINGLE",
+  "optionConfig": {
+    "apiUrl": "https://api.example.com/countries",
+    "valuePath": "code",
+    "labelPath": "name.common",
+    "sortBy": "name.common",
+    "sortDirection": "ASC"
+  }
+}
+```
+
+**Searchable Dropdown (Local Filtering):**
+
+Add a search input inside the dropdown panel to filter options client-side. Works with both `SINGLE` and `MULTIPLE` subtypes.
+
+```json
+{
+  "name": "country",
+  "label": "Select Country",
+  "type": "DROPDOWN",
+  "subType": "SINGLE",
+  "optionConfig": {
+    "apiUrl": "https://api.example.com/countries",
+    "valuePath": "code",
+    "labelPath": "name",
+    "searchConfig": {
+      "enabled": true
+    }
+  }
+}
+```
+
+**Searchable Dropdown (Server-side Filtering via GET):**
+
+For large datasets, configure the dropdown to query the API as the user types. The search term is appended as a query parameter to the existing API URL.
+
+```json
+{
+  "name": "academicSubject",
+  "label": "Academic Subject",
+  "type": "DROPDOWN",
+  "subType": "MULTIPLE",
+  "optionConfig": {
+    "apiUrl": "https://api.example.com/subjects",
+    "dataPath": "elements",
+    "labelPath": "name",
+    "valuePath": "code",
+    "searchConfig": {
+      "enabled": true,
+      "mode": "server",
+      "searchKey": "searchTerm",
+      "minSearchLength": 3,
+      "debounceTime": 400
+    }
+  }
+}
+```
+
+**Loading Spinner (`showLoader`):**
+
+To display an inline spinning loader during API option requests (e.g. for dynamic or dependent dropdowns), set `"showLoader": true` inside `optionConfig`. This works for both custom searchable dropdowns (`.mini-spinner`) and native single-select dropdowns (`.native-select-spinner`).
+
+```json
+{
+  "name": "district",
+  "label": "District",
+  "type": "DROPDOWN",
+  "subType": "SINGLE",
+  "optionConfig": {
+    "apiUrl": "https://api.example.com/districts",
+    "dataPath": "elements",
+    "showLoader": true
+  }
+}
+```
+
+> **Native Select Loader Note:** For non-searchable single-select dropdowns (`config.subType === 'SINGLE' && !isSearchableDropdown`), the library wraps the native `<select>` element and overlays an absolute spinner (`.native-select-spinner`) positioned at `right: 2.5rem` with `pointer-events: none`, ensuring that the native browser dropdown clicks remain fully accessible while visually feedbacking options loading.
+
+**Selected Option Label Persistence (Server-side Search):**
+
+When using `mode: "server"`, the dropdown only displays options fetched from the API (such as the first page of results or matching search results). If a form is loaded in `EDIT` mode, the selected value might not be in the initial page of options, causing the field to appear blank in the UI.
+
+To prevent this, you can pass the selected options' metadata (label, code, details) to `<lib-smart-form>` using the `selectedOptionsData` input property. This caches the selected item details and ensures they are merged into the dropdown's option list even after searches or paginated listings are fetched.
+
+#### Example MFE Integration
+
+##### 1. Form Schema Config (JSON)
+```json
+{
+  "name": "academicSubject",
+  "label": "Academic Subject",
+  "type": "DROPDOWN",
+  "subType": "SINGLE",
+  "optionConfig": {
+    "apiUrl": "https://api.example.com/subjects",
+    "valuePath": "id",
+    "labelPath": "name",
+    "searchConfig": {
+      "enabled": true,
+      "mode": "server",
+      "searchKey": "q"
+    }
+  }
+}
+```
+
+##### 2. MFE Parent Component Markup
+```html
+<lib-smart-form
+  [formJson]="formSchema"
+  [initialValues]="formInitialValues"
+  [selectedOptionsData]="selectedOptionsData"
+  [mode]="'EDIT'"
+  (submit)="onSubmit($event)">
+</lib-smart-form>
+```
+
+##### 3. MFE Parent Component Controller (TypeScript)
+```typescript
+import { Component, OnInit } from '@angular/core';
+
+@Component({
+  selector: 'app-subject-edit',
+  templateUrl: './subject-edit.component.html'
+})
+export class SubjectEditComponent implements OnInit {
+  formSchema = `...`; // Schema JSON from Step 1
+
+  // 1. Keep initialValues flat with primitive codes/IDs
+  formInitialValues = {
+    academicSubject: 8
+  };
+
+  // 2. Provide the full metadata for the selected options so the form can display the label
+  selectedOptionsData = {
+    // For single select: pass a single object
+    academicSubject: {
+      id: 8,
+      name: "Chemistry"
+    }
+    // For multi-select: pass an array of objects
+    // academicSubjects: [
+    //   { id: 8, name: "Chemistry" },
+    //   { id: 10, name: "Mathematics" }
+    // ]
+  };
+
+  onSubmit(payload: any) {
+    // Submits the standard flat form payload containing raw codes:
+    // payload: { academicSubject: 8 }
+    console.log('Form Submitted:', payload);
+  }
+}
+```
+
+**Dropdown Caching & Redundant API Call Optimization:**
+
+To prevent redundant API queries to the backend during user interaction, the Dropdown component caches fetched options in `localOptionList`.
+
+1. **Overlay Opening**: When the dropdown overlay panel opens, the component triggers the API query *only* if the `localOptionList` is currently empty. If options have already been fetched, it loads options instantly from the cache, avoiding subsequent duplicate network calls.
+2. **Overlay Closing**: When closing the dropdown (e.g. user selects an option, clicks outside, or hits the Escape key), the search input filter is cleared locally by passing `false` to `resetDropdownSearch(false)`. This clears the text search box but bypasses the option-loading API request completely.
+3. **Typing and Filtering**: When the user explicitly types in the search input box, the component automatically bypasses the cache check and queries the backend with the search query parameters (`searchKey` / `searchString`).
+4. **Dependency-Based Cache Invalidation**: If parent dependency fields change (e.g., changing the Academic Subject which invalidates the Learning Outcomes options), the dropdown cache is cleared reactively (`localOptionList = []`), forcing a fresh backend query the next time the dropdown is opened.
+
+##### Example Searchable Server-Side Dropdown Config (JSON)
+```json
+{
+  "name": "academicSubject",
+  "label": "Academic Subject",
+  "type": "DROPDOWN",
+  "subType": "SINGLE",
+  "optionConfig": {
+    "apiUrl": "gateway/commons-mdm-service/api/v1/subjects",
+    "valuePath": "id",
+    "labelPath": "name[0].text",
+    "searchConfig": {
+      "enabled": true,
+      "mode": "server",
+      "searchKey": "searchTerm",
+      "minSearchLength": 3,
+      "debounceTime": 400
+    }
+  }
+}
+```
+
+**Select All (Multi-Select Only):**
+
+For `MULTIPLE` dropdowns, add a "Select All" checkbox at the top of the option list. Can be combined with `searchConfig` — when a search filter is active, "Select All" toggles only the visible (filtered) options.
+
+```json
+{
+  "name": "skills",
+  "label": "Skills",
+  "type": "DROPDOWN",
+  "subType": "MULTIPLE",
+  "optionConfig": {
+    "optionList": [
+      { "label": "JavaScript", "code": "JS" },
+      { "label": "Python", "code": "PY" },
+      { "label": "Java", "code": "JAVA" },
+      { "label": "Go", "code": "GO" }
+    ],
+    "showSelectAll": true,
+    "searchConfig": {
+      "enabled": true
+    }
+  }
+}
+```
+
+#### Dropdown Search Configuration (`searchConfig`)
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `enabled` | `boolean` | — | **Required.** Displays a search input inside the dropdown panel. |
+| `mode` | `'local' \| 'server'` | `'local'` | `local`: filters client-side. `server`: queries the API on typing via GET. |
+| `searchKey` | `string` | `'search'` | Query parameter key for the search term sent to the API. Only used in `server` mode. |
+| `minSearchLength` | `number` | `3` | Minimum characters required before triggering a server-side search. Only used in `server` mode. |
+| `debounceTime` | `number` | `300` | Debounce delay in milliseconds before firing the search. |
+
+#### Select All Configuration
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `showSelectAll` | `boolean` | `false` | Renders a "Select All" checkbox at the top of a `MULTIPLE` select dropdown. |
+
+#### i18n Labels for Search & Select All
+
+The following label keys can be provided via the `labels` input to customise the UI text:
+
+| Key | Default | Description |
+| :--- | :--- | :--- |
+| `SEARCH_PLACEHOLDER` | `Search...` | Placeholder text for the search input. |
+| `SELECT_ALL` | `Select All` | Label for the Select All checkbox. |
+| `NO_MATCHING_OPTIONS` | `No options match your search` | Shown when the search filter yields no results. |
+
+### 5. Radio Button (RADIO)
+
+```json
+{
+  "name": "gender",
+  "label": "Gender",
+  "type": "RADIO",
+  "subType": "SINGLE",
+  "required": true,
+  "optionConfig": {
+    "optionList": [
+      { "label": "Male", "code": "M" },
+      { "label": "Female", "code": "F" }
+    ]
+  }
+}
+```
+
+### 6. Checkbox (CHECKBOX)
+
+**SubTypes:** `BOOL`, `LIST`
+
+```json
+{
+  "name": "agreeToTerms",
+  "label": "I agree to terms",
+  "type": "CHECKBOX",
+  "subType": "BOOL",
+  "required": true
+}
+```
+
+### 7. Chip Selection (CHIP)
+
+```json
+{
+  "name": "skills",
+  "label": "Skills",
+  "type": "CHIP",
+  "subType": "MULTIPLE",
+  "optionConfig": {
+    "optionList": [
+      { "label": "JavaScript", "code": "JS" },
+      { "label": "Python", "code": "PY" }
+    ]
+  }
+}
+```
+
+### 8. Switch (SWITCH)
+
+```json
+{
+  "name": "notifications",
+  "label": "Enable Notifications",
+  "type": "SWITCH",
+  "subType": "BOOL",
+  "defaultValue": true
+}
+```
+
+### 9. Rating (RATING)
+
+```json
+{
+  "name": "rating",
+  "label": "Rate your experience",
+  "type": "RATING",
+  "subType": "STAR",
+  "ratingConfig": {
+    "maxRating": 5,
+    "allowHalf": true
+  }
+}
+```
+
+### 10. File Upload (FILE_UPLOAD)
+
+Provides a drag-and-drop area with file-type and file-size validation. The field value is an array of `UploadedFile` objects. This field uses a unified `attachmentConfig` for all upload types (PDF, Images, Documents, etc.).
+
+**SubTypes:** `SINGLE`
+
+```json
+{
+  "name": "profilePicture",
+  "label": "Profile Picture",
+  "type": "FILE_UPLOAD",
+  "subType": "SINGLE",
+  "attachmentConfig": {
+    "multiple": false,
+    "maxSizeMB": 2,
+    "accept": "image/*",
+    "acceptLabel": "JPG, PNG, SVG (max 2 MB)"
+  }
+}
+```
+
+| `attachmentConfig` key | Type    | Description                                                  |
+| ---------------------- | ------- | ------------------------------------------------------------ |
+| `multiple`             | boolean | Allow multiple file selection (default: `false`)             |
+| `maxFiles`             | number  | Max number of files when `multiple: true` (default: `10`)    |
+| `maxSizeMB`            | number  | Max file size per file in MB (default: `10`)                 |
+| `accept`               | string  | Accepted MIME types / extensions, e.g. `".pdf,.jpg,image/*"` |
+| `acceptLabel`          | string  | Human-readable hint shown in the drop zone                   |
+
+### 11. Generated Field (GENERATED)
+
+Auto-calculated fields that update whenever dependent field values change.
+
+```json
+{
+  "name": "fullName",
+  "label": "Full Name",
+  "type": "GENERATED",
+  "subType": "FORMULA",
+  "generatedConfig": {
+    "formula": "function fullName(first, last) { return (first || '') + ' ' + (last || ''); }",
+    "variables": ["firstName", "lastName"]
+  }
+}
+```
+
+### 12. Geography Dynamic (GEOGRAPHY_DYNAMIC)
+
+Renders a cascading hierarchy of geography dropdowns (e.g. Country → State → District) by fetching a hierarchy template from an MDM API. When the hierarchy has a **branch point** (e.g. State → RURAL | URABN), an **Area Type** selector is automatically inserted so the user can choose which path to follow.
+
+**Branch point behavior**
+
+- The Area Type dropdown is generated automatically from the branch children (e.g. "Rural" / "Urban").
+- Selecting a branch value shows only the dropdowns belonging to that path (District, Taluka, Village …).
+- Structural branch-type nodes (RURAL, URABN) are **not** rendered as data dropdowns — only their descendants are. The first descendant depends on the last linear parent before the fork (e.g. State), not on the branch node itself.
+- If the form is pre-populated with an `areaType` value (edit mode), the downstream dropdowns are visible immediately.
+
+```json
+{
+  "name": "address",
+  "label": "Address",
+  "type": "GEOGRAPHY_DYNAMIC",
+  "geographyConfig": {
+    "templateApi": {
+      "apiUrl": "https://api.example.com/mdm/hierarchy-templates",
+      "listPath": "templates",
+      "select": "byCode",
+      "selectCode": "ADDRESS_TEMPLATE"
+    },
+    "dataApi": {
+      "apiUrl": "https://api.example.com/mdm/data/{classCode}",
+      "dataPath": "elements",
+      "labelPath": "name[0].text",
+      "valuePath": "code"
+    },
+    "structure": {
+      "rootCodePath": "rootClassCode",
+      "hierarchyListPath": "mdmclasshierarchytemplatestructList",
+      "parentField": "parentCode",
+      "childField": "childCode"
+    },
+    "field": {
+      "colSpan": 4,
+      "payloadPathPrefix": "addressInfo",
+      "branchSubType": "SINGLE",
+      "dependency": {
+        "paramName": "parentDataCode"
+      },
+      "nodes": {
+        "REGION.COUNTRY": { "label": "Country", "required": true },
+        "REGION.STATE":   { "label": "State",   "payloadField": "stateCode" }
+      }
+    }
+  }
+}
+```
+
+**`field` configuration keys**
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `colSpan` | `number` | `12` | Column span applied to every generated dropdown |
+| `payloadPathPrefix` | `string` | `''` | Dot-notation prefix prepended to all generated `payloadPath` values |
+| `branchSubType` | `'SINGLE' \| 'MULTIPLE'` | `'SINGLE'` | Sub-type for the auto-generated Area Type selector |
+| `dependency.paramName` | `string` | `'parentDataCode'` | Query parameter name sent when loading child data |
+| `nodes` | `Record<string, object>` | `{}` | Per-node overrides keyed by class code — supports `label`, `name`, `payloadField`, `required`, `placeholder`, `hidden`, `noDependency` |
+
+### 13. Rich Text Editor (RICH_TEXT)
+
+Provides a WYSIWYG rich text editor using Quill.
+
+```json
+{
+  "name": "description",
+  "label": "Detailed Description",
+  "type": "RICH_TEXT",
+  "required": true,
+  "richTextConfig": {
+    "placeholder": "Enter detailed information here...",
+    "height": "250px",
+    "headerConfig": ["bold", "italic", "underline", "font", "size", "color", "link", "image", "video"]
+  }
+}
+```
+
+`headerConfig` controls which toolbar buttons are shown, in order. If omitted, it defaults to:
+`["bold", "italic", "underline", "font", "size", "color", "link", "image", "video"]`.
+
+Supported tokens: `bold`, `italic`, `underline`, `strike`, `blockquote`, `code`, `font`, `size`, `color`, `background`, `align`, `header1`, `header2`, `orderedList`, `bulletList`, `subscript`, `superscript`, `indentMinus`, `indentPlus`, `link`, `image`, `video`, `clean`.
+
+### 14. Link List (LINK_LIST)
+
+Allows users to manage a list of URLs dynamically. Provides a text input box with a trailing plus icon to add links, displaying them as a list above or below the input field.
+
+**Configuration Properties (`linkListConfig`):**
+
+| Property | Type | Description |
+|---|---|---|
+| `listPosition` | `'top' \| 'bottom'` | Renders the link list above or below the input field (default: `'bottom'`). |
+| `editable` | `boolean` | Allows inline editing of existing links in the list (default: `true`). |
+| `deleteable` | `boolean` | Shows a delete action button on list items (default: `true`). |
+| `valueFormat` | `'string' \| 'array' \| 'object'` | Format in which data is stored in the form control: `'string'` (separated by `separator`), `'array'` (array of strings), or `'object'` (array of objects) (default: `'string'`). |
+| `separator` | `string` | Character used to separate links when `valueFormat` is `'string'` (default: `','`). |
+| `urlKey` | `string` | The object key used to store/load the link URL when `valueFormat` is `'object'` (default: `'linkUrl'`). |
+| `idField` | `string` | The object key representing the link identifier when resolving API placeholders (default: `'id'`). |
+| `deleteApiUrl` | `string` | Optional API endpoint to execute an HTTP DELETE call upon removing a saved item (e.g. `/api/v1/links/:id`). |
+| `editApiUrl` | `string` | Optional API endpoint to execute an HTTP PUT call upon editing a saved item (e.g. `/api/v1/links/:id`). |
+| `pattern` | `string` | Regular expression pattern for validating each link (default URL validator regex: `^https?://([a-zA-Z0-9\-]+\.)+[a-zA-Z]{2,}(/\S*)?$`). |
+| `patternMessage` | `string` | Custom error message displayed if pattern validation fails. |
+| `colSpan` | `number` | Grid column span (1-12) for each list item in the 12-column grid. E.g., `6` for two columns side-by-side (default: `12`). |
+
+**Example Config (Storing as an Array of Objects):**
+
+```json
+{
+  "name": "externalLinks",
+  "label": "External Links",
+  "type": "LINK_LIST",
+  "placeholder": "Enter link...",
+  "colSpan": 12,
+  "linkListConfig": {
+    "listPosition": "bottom",
+    "editable": true,
+    "deleteable": true,
+    "valueFormat": "object",
+    "urlKey": "linkUrl"
+  }
+}
+```
+
+**Example Config (Storing as a Comma-Separated String):**
+
+```json
+{
+  "name": "externalLinks",
+  "label": "External Links",
+  "type": "LINK_LIST",
+  "placeholder": "Enter link...",
+  "colSpan": 12,
+  "linkListConfig": {
+    "listPosition": "top",
+    "editable": true,
+    "deleteable": true,
+    "valueFormat": "string",
+    "separator": ","
+  }
+}
+```
+
+**Example Config (Two-Column Layout with Regex Validation):**
+
+```json
+{
+  "name": "externalLinks",
+  "label": "External Links",
+  "type": "LINK_LIST",
+  "placeholder": "Enter link...",
+  "colSpan": 12,
+  "linkListConfig": {
+    "listPosition": "bottom",
+    "editable": true,
+    "deleteable": true,
+    "valueFormat": "object",
+    "urlKey": "linkUrl",
+    "colSpan": 6,
+    "pattern": "^https?://([a-zA-Z0-9\\-]+\\.)+com(/\\S*)?$",
+    "patternMessage": "Only .com domain links are allowed"
+  }
+}
+```
+
+---
+
+## Layout System
+
+### ROW Layout
+
+Use `type: "ROW"` to place multiple fields horizontally in a 12-column CSS grid. Each child can declare a `colSpan` (1–12). If omitted, the available columns are divided equally among all children.
+
+```json
+{
+  "type": "ROW",
+  "subType": "HORIZONTAL",
+  "children": [
+    {
+      "name": "firstName",
+      "label": "First Name",
+      "type": "TEXT_INPUT",
+      "subType": "SHORT",
+      "colSpan": 6
+    },
+    {
+      "name": "lastName",
+      "label": "Last Name",
+      "type": "TEXT_INPUT",
+      "subType": "SHORT",
+      "colSpan": 6
+    }
+  ]
+}
+```
+
+### `colSpan` on Section-level Fields
+
+A non-ROW field that is a direct child of a section can also carry a `colSpan` to participate in the section-level 12-column grid:
+
+```json
+{
+  "name": "description",
+  "label": "Description",
+  "type": "TEXT_INPUT",
+  "subType": "LONG",
+  "colSpan": 8
+}
+```
+
+### `colSpan` Reference
+
+| `colSpan` value | Effective width |
+| --------------- | --------------- |
+| 3               | 25%             |
+| 4               | 33%             |
+| 6               | 50%             |
+| 8               | 67%             |
+| 9               | 75%             |
+| 12 (default)    | 100%            |
+
+---
+
+## Configuration Options
+
+### Form Schema
+
+```typescript
+interface FormSchema {
+  entityType: string;
+  label: string; // Can be an i18n key
+  formType: "SECTION" | "STEPPER";
+  showTitle?: boolean;
+  showDescription?: boolean;
+  description?: string; // Can be an i18n key
+  metadata?: { [key: string]: any };
+  sectionConfig?: SectionConfig;
+  stepperConfig?: StepperConfig;
+  submitConfig?: SubmitConfig;
+  editConfig?: EditConfig; // Config for form editing (GET to load, PATCH/PUT to submit)
+  actionBarConfig?: ActionBarConfig; // Flexible action bar (Cancel / Draft / Submit)
+  showActions?: boolean;
+  token?: string; // Full auth token (e.g. "Bearer eyJ…") — applied to all API calls
+  tokenHeader?: string; // HTTP header name (default: "Authorization")
+}
+```
+
+### Action Bar Config
+
+The `actionBarConfig` defines the buttons rendered at the bottom of the form. It uses a **unified, flexible list of buttons** where each button has its own visual style and behavior-driven action.
+
+#### Unified Button Model
+
+In the new model, a button is **only visual** (label, variant, alignment, order). All logic (what happens when clicked) is delegated to an `action` object of type `ActionConfig`.
+
+| Action `kind` | Behaviour |
+|---------------|-----------|
+| `'submit'`    | Validates the form and calls the central `submitConfig` or `editConfig` API. |
+| `'draft'`     | Saves the form data without full validation. Merges `extraPayload` if provided. |
+| `'navigate'`  | Simply navigates to the `redirectUrl`. No API call. |
+| `'api'`       | Fires a standalone API call (`apiUrl`, `method`), then optionally navigates. |
+| `'emit'`      | Emits the `actionClick` output event with the button `id` and form data. |
+| `'next'`      | Advances to the next step (Stepper forms only). |
+| `'prev'`      | Goes back to the previous step (Stepper forms only). |
+
+#### Interfaces
+
+```typescript
+interface ActionBarConfig {
+  /** Explicitly ordered list of action buttons. */
+  buttons: ActionButtonConfig[];
+}
+
+interface ActionButtonConfig {
+  id: string;                    // Unique identifier for the button
+  label?: string;                // i18n key or plain text
+  variant?: string;              // lib-button variant (primary, outline, etc.)
+  alignment?: 'left'|'right';   // Which side of the bar to place the button (default: 'right')
+  order?: number;                // Display order within the alignment group
+  hidden?: boolean;              // Hide the button
+  disabled?: boolean;            // Disable the button
+  showOnLastStepOnly?: boolean;  // Section Stepper only: show this button only on the last step
+  action: ActionConfig;          // The behavior triggered on click
+}
+
+interface ActionConfig {
+  kind: 'submit' | 'draft' | 'navigate' | 'api' | 'emit' | 'next' | 'prev';
+  redirectUrl?: string;      // Used by 'navigate', 'api', 'draft', and 'submit'
+  apiUrl?: string;           // Required for 'api' kind
+  method?: string;           // HTTP method for 'api' actions (default: 'POST')
+  extraPayload?: object;     // Static payload for 'api' or 'draft' saves
+  successMessage?: string;   // Custom success snackbar message
+  errorMessage?: string;     // Custom error snackbar message
+  snackbarConfig?: object;   // Snackbar display options
+}
+```
+
+#### Example — Standard Cancel, Draft, and Submit
+
+This configuration places a "Cancel" button on the left that navigates away, and "Save as Draft" + "Submit" buttons on the right.
+
+```json
+{
+  "actionBarConfig": {
+    "buttons": [
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "variant": "outline",
+        "alignment": "left",
+        "action": { "kind": "navigate", "redirectUrl": "/dashboard" }
+      },
+      {
+        "id": "draft",
+        "label": "Save as Draft",
+        "variant": "secondary",
+        "alignment": "right",
+        "action": { "kind": "draft", "extraPayload": { "status": "DRAFT" } }
+      },
+      {
+        "id": "submit",
+        "label": "Submit",
+        "variant": "primary",
+        "alignment": "right",
+        "action": { "kind": "submit" }
+      }
+    ]
+  }
+}
+```
+
+#### Example — Stepper with Back/Next and a Custom Finish Button
+
+```json
+{
+  "actionBarConfig": {
+    "buttons": [
+      {
+        "id": "back",
+        "label": "Back",
+        "alignment": "left",
+        "action": { "kind": "prev" }
+      },
+      {
+        "id": "save-and-exit",
+        "label": "Save & Exit",
+        "alignment": "right",
+        "variant": "outline",
+        "action": { "kind": "api", "apiUrl": "/api/v1/sessions/save-progress" }
+      },
+      {
+        "id": "next",
+        "label": "Next Step",
+        "alignment": "right",
+        "variant": "primary",
+        "action": { "kind": "submit" }
+      }
+    ]
+  }
+}
+```
+
+#### Notes
+
+- **Alignment**: Buttons with `alignment: 'left'` are grouped on the left side. `alignment: 'right'` (the default) are on the right. Both groups use `flexbox` for layout, pushing them to opposite edges of the form.
+- **Ordering**: Within each side, buttons are sorted by the `order` property (numeric, ascending). If `order` is omitted, they appear in the order defined in the JSON array.
+- **Custom Actions**: Use `kind: 'emit'` to handle logic in your parent component. Whenever clicked, the `<lib-smart-form>` will emit an `(actionClick)` event containing the button's `id` and the current form data.
+- **Draft Behavior**: Just like the legacy mode, `'kind': 'draft'` skips required field validation and collects whatever data is currently in the form.
+- **`showOnLastStepOnly`**: When `true` and the form is in **Section Stepper** mode, the button is hidden on all intermediate steps and only appears on the last step. Has no effect in regular (non-stepper) layouts — the button always shows there. Ideal for Submit buttons that should not be reachable until the user has navigated through all steps.
+
+### Section Config
+
+```typescript
+interface SectionConfig {
+  children: FieldConfig[];
+  allowMulti?: boolean; // Enables repeater mode — see Repeatable Sections
+  name?: string; // Required when allowMulti is true (used as FormArray key)
+  label?: string; // Can be an i18n key
+  isEnabled?: boolean; // Static flag to explicitly hide the entire section if false
+}
+```
+
+### Submit & Edit Configs
+
+```typescript
+interface SubmitConfig {
+  apiUrl: string;
+  method?: "POST" | "PUT" | "PATCH";
+  successMessage?: string; // Can be an i18n key
+  errorMessage?: string; // Can be an i18n key
+  redirectUrl?: string; // Redirect after success
+  extraPayload?: { [key: string]: any }; // Static extra fields for payload
+  snackbarConfig?: SnackbarConfigOverride; // Customizes the API feedback alerts
+}
+
+interface EditConfig {
+  loadApiUrl: string; // Custom GET API to load existing form data
+  submitApiUrl: string; // PATCH/PUT/POST API for updating
+  submitMethod?: "PATCH" | "PUT" | "POST";
+  successMessage?: string;
+  errorMessage?: string;
+  redirectUrl?: string;
+  extraPayload?: { [key: string]: any };
+  snackbarConfig?: SnackbarConfigOverride;
+}
+
+interface SnackbarConfigOverride {
+  duration?: number; // Auto-dismiss time (default 5000)
+  horizontalPosition?: "start" | "center" | "end" | "left" | "right";
+  verticalPosition?: "top" | "bottom";
+  showCloseButton?: boolean;
+}
+```
+
+### Field Config (key properties)
+
+```typescript
+interface FieldConfig {
+  name?: string;
+  label?: string; // Can be an i18n key
+  type: string;
+  subType: string;
+  required?: boolean;
+  disabled?: boolean;
+  defaultValue?: any;
+  placeholder?: string; // Can be an i18n key
+  hint?: string; // Can be an i18n key
+  colSpan?: number; // Column span in 12-column grid (1–12)
+  payloadPath?: string; // Dot-notation path for nested payload mapping (e.g., 'status.code')
+  visibilityExpression?: string;
+  isEnabled?: boolean; // Static flag to explicitly disable/hide the field if false
+  readonly?: boolean; // Whether the field is read-only (shows lock icon)
+  suffixActionIcons?: SuffixActionIcon[]; // Clickable action icons inside the input
+  sectionConfig?: SectionConfig;
+  textConfig?: TextConfig;
+  numberConfig?: NumberConfig;
+  dateConfig?: DateConfig;
+  timeConfig?: TimeConfig;
+  optionConfig?: OptionConfig;
+  attachmentConfig?: AttachmentConfig;
+  ratingConfig?: RatingConfig;
+  generatedConfig?: GeneratedConfig;
+  richTextConfig?: RichTextConfig;
+  children?: FieldConfig[]; // For ROW and GROUP fields
+}
+
+interface SuffixActionIcon {
+  icon: string;      // Material icon name (e.g. 'edit', 'refresh')
+  actionId: string;  // Unique ID emitted on click
+  tooltip?: string;  // Optional tooltip shown on hover
+  color?: string;    // Optional custom color override (e.g. '#16A34A')
+}
+
+interface AttachmentConfig {
+  multiple?: boolean;
+  maxFiles?: number;
+  maxSizeMB?: number;
+  accept?: string;
+  acceptLabel?: string;
+  allowedExtensions?: string[]; // Legacy
+}
+
+interface RichTextConfig {
+  height?: string; // CSS height for the editor (e.g. "200px")
+  placeholder?: string; // Custom placeholder text
+  maxLength?: number;
+  showCharCount?: boolean;
+  headerConfig?: string[]; // Toolbar tokens to show, in order (default: bold/italic/underline/font/size/color/link/image/video)
+}
+```
+
+---
+
+## Advanced Features
+
+### 1. Conditional Visibility
+
+Show/hide fields based on other field values using a JavaScript-like expression:
+
+```json
+{
+  "name": "otherReason",
+  "label": "Please specify",
+  "type": "TEXT_INPUT",
+  "subType": "SHORT",
+  "visibilityExpression": "reason === 'OTHER'",
+  "required": true
+}
+```
+
+The expression is evaluated against the live form data. When a field is hidden its control is disabled so its value is excluded from submission.
+
+### 2. Auto-Calculated Fields
+
+Fields that automatically update based on other fields:
+
+```json
+{
+  "name": "total",
+  "label": "Total Amount",
+  "type": "GENERATED",
+  "subType": "FORMULA",
+  "generatedConfig": {
+    "formula": "function total(price, quantity) { return (price || 0) * (quantity || 0); }",
+    "variables": ["price", "quantity"]
+  }
+}
+```
+
+### 3. Repeatable Sections (`allowMulti` on GROUP)
+
+Allow users to add multiple instances of a section (e.g., multiple work experiences):
+
+```json
+{
+  "type": "GROUP",
+  "subType": "SECTION",
+  "sectionConfig": {
+    "label": "Work Experience",
+    "allowMulti": true,
+    "name": "experienceList",
+    "children": [
+      {
+        "name": "company",
+        "label": "Company",
+        "type": "TEXT_INPUT",
+        "subType": "SHORT",
+        "required": true
+      },
+      {
+        "name": "position",
+        "label": "Position",
+        "type": "TEXT_INPUT",
+        "subType": "SHORT",
+        "required": true
+      }
+    ]
+  }
+}
+```
+
+- `name` is **required** when `allowMulti: true` — it becomes the `FormArray` key on the root `FormGroup`.
+- Each instance is a completely isolated `FormGroup`; data does not leak between instances.
+- The submitted value for this key is an **array of objects**, e.g. `{ "experienceList": [{ "company": "...", "position": "..." }, ...] }`.
+- **Add is gated on completeness.** Clicking "Add" is refused if the *previous* instance still has an invalid required field — that instance is re-expanded and marked touched (its errors render) instead of a new blank row being added. This prevents users from stacking up several incomplete rows with no indication anything is wrong until final submit.
+- **Sibling dropdowns auto-exclude taken values.** A single-select `DROPDOWN` field inside a repeater automatically hides values already chosen by *other* instances of the same repeater — e.g. picking "English" in Language Details #1 removes it from Language Details #2's option list. This is automatic for any single-select `DROPDOWN` in a repeater; no schema config is needed. It does **not** apply to `MULTIPLE`-subtype dropdowns.
+
+### 4. Cross-Field Match Validation (e.g. confirm password)
+
+Use `textConfig.matchField` on the confirmation field to enforce equality:
+
+```json
+{
+  "name": "confirmPassword",
+  "label": "Confirm Password",
+  "type": "TEXT_INPUT",
+  "subType": "PASSWORD",
+  "required": true,
+  "textConfig": { "matchField": "password" }
+}
+```
+
+- Validation fires bi-directionally: if the user edits the source field after confirming, the error clears automatically.
+- Error key: `passwordMismatch`, shown as "Passwords do not match".
+
+### 5. Row Layouts with Column Spans
+
+Display multiple fields in a row with fine-grained width control:
+
+```json
+{
+  "type": "ROW",
+  "subType": "HORIZONTAL",
+  "children": [
+    {
+      "name": "shortCode",
+      "label": "Short Code",
+      "type": "TEXT_INPUT",
+      "subType": "SHORT",
+      "colSpan": 3
+    },
+    {
+      "name": "donorType",
+      "label": "Donor Type",
+      "type": "DROPDOWN",
+      "subType": "SINGLE",
+      "colSpan": 3
+    },
+    {
+      "name": "regNumber",
+      "label": "Reg. Number",
+      "type": "TEXT_INPUT",
+      "subType": "SHORT",
+      "colSpan": 3
+    },
+    {
+      "name": "country",
+      "label": "Country",
+      "type": "DROPDOWN",
+      "subType": "SINGLE",
+      "colSpan": 3
+    }
+  ]
+}
+```
+
+### 6. Suffix Action Icons
+
+Add clickable action icons inside `TEXT_INPUT` (short text, email, phone) and `NUMBER_INPUT` fields to trigger custom logic in the host application (e.g. password visibility toggling, code validation, API lookup).
+
+```json
+{
+  "name": "promoCode",
+  "label": "PROMO_CODE.LABEL",
+  "type": "TEXT_INPUT",
+  "subType": "SHORT",
+  "suffixActionIcons": [
+    {
+      "icon": "refresh",
+      "actionId": "regenerate_code",
+      "tooltip": "Regenerate Promo Code",
+      "color": "#1E3A8A"
+    },
+    {
+      "icon": "check_circle",
+      "actionId": "verify_code",
+      "tooltip": "Verify Validity",
+      "color": "#16A34A"
+    }
+  ]
+}
+```
+
+When clicked, the `(suffixActionClick)` output event is emitted. The host application catches this event to run specific actions (such as generating a new promo code or verifying its validity).
+
+> [!NOTE]
+> Suffix action icons are ignored if the field is set to `readonly: true`. In that state, the default security lock icon (`lock`) takes visual precedence.
+
+---
+
+## i18n / Translation Support
+
+The `SmartFormComponent` accepts a `[labels]` input that is a **flat key–value map** of i18n strings (or an object with a `labelsObject` property following the same pattern used by `ConfigurableFormComponent`).
+
+When `labels` is provided, the component recursively walks the parsed schema **before rendering** and replaces every matching key with its translated value.
+
+### Action Labels
+
+The form action buttons (Next, Submit, Previous, Add, Remove) and file upload error messages can be localized by providing keys in the `labels` property of the `FormSchema`.
+
+```json
+{
+  "entityType": "USER",
+  "label": "FORM.TITLE",
+  "formType": "SECTION",
+  "labels": {
+    "nextLabel": "APP.BUTTON.NEXT",
+    "submitLabel": "APP.BUTTON.SUBMIT",
+    "previousLabel": "APP.BUTTON.PREVIOUS",
+    "addLabel": "APP.BUTTON.ADD",
+    "removeLabel": "APP.BUTTON.REMOVE",
+    "fileTypeError": "\"{fileName}\" is not a supported file type.",
+    "fileSizeError": "\"{fileName}\" exceeds the maximum allowed size of {maxSizeMB} MB.",
+    "maxFilesError": "Maximum {maxFiles} files allowed.",
+    "fileUploadFailed": "Failed to upload \"{fileName}\". Please try again.",
+    "fileDeleteFailed": "Failed to delete \"{fileName}\". Please try again."
+  }
+}
+```
+
+If a mapping is not provided, the buttons and messages fall back to default English strings.
+
+**File upload label placeholders**
+
+| Label key | Dynamic placeholders | Default English text |
+|---|---|---|
+| `fileTypeError` | `{fileName}` | `"{fileName}" is not a supported file type.` |
+| `fileSizeError` | `{fileName}`, `{maxSizeMB}` | `"{fileName}" exceeds the maximum allowed size of {maxSizeMB} MB.` |
+| `maxFilesError` | `{maxFiles}` | `Maximum {maxFiles} files allowed.` |
+| `fileUploadFailed` | `{fileName}` | `Failed to upload "{fileName}". Please try again.` |
+| `fileDeleteFailed` | `{fileName}` | `Failed to delete "{fileName}". Please try again.` |
+
+### Translatable Schema Properties
+
+| Property path                           | Description                                    |
+| --------------------------------------- | ---------------------------------------------- |
+| `schema.label`                          | Form title                                     |
+| `schema.description`                    | Form description                               |
+| `schema.submitConfig.successMessage`    | Success alert text                             |
+| `schema.submitConfig.errorMessage`      | Error alert text                               |
+| `sectionConfig.label`                   | Section heading                                |
+| `field.label`                           | Field label                                    |
+| `field.placeholder`                     | Field placeholder                              |
+| `field.hint`                            | Field hint text                                |
+| `field.textConfig.patternMessage`       | Custom pattern error message                   |
+| `field.attachmentConfig.acceptLabel`    | File drop-zone hint (for all attachment types) |
+| `field.optionConfig.optionList[].label` | Static option labels                           |
+| `schema.labels.nextLabel`               | Key for "Next" button text (Stepper)           |
+| `schema.labels.submitLabel`             | Key for "Submit" button text                   |
+| `schema.labels.previousLabel`           | Key for "Previous" button text (Stepper)       |
+| `schema.labels.addLabel`                | Key for "Add" button text (Repeater)           |
+| `schema.labels.removeLabel`             | Key for "Remove" button text (Repeater)        |
+| `schema.labels.fileTypeError`           | File upload: unsupported file type error       |
+| `schema.labels.fileSizeError`           | File upload: file too large error              |
+| `schema.labels.maxFilesError`           | File upload: too many files error              |
+| `schema.labels.fileUploadFailed`        | File upload: API upload failure message        |
+| `schema.labels.fileDeleteFailed`        | File upload: API delete failure message        |
+
+> **Note:** Translation logic is centralized in the `SmartFormTranslationUtils` class. If you add new translatable properties to the `FormSchema` or `FieldConfig` models, ensure they are also registered in the `SmartFormTranslationUtils.translateSchema` method to be correctly processed.
+
+Translation is applied recursively — it covers fields inside `ROW` children, `GROUP` children, nested `sectionConfig` sections, and all stepper steps.
+
+### Usage
+
+```html
+<lib-smart-form
+  [formJson]="formJson"
+  [labels]="labels"
+  (submit)="onSubmit($event)"
+>
+</lib-smart-form>
+```
+
+```typescript
+// Flat map — keys exactly match the strings used in the JSON schema
+labels = {
+  "SMART_FORM.TITLE": "User Registration",
+  "SMART_FORM.FIELD.FIRST_NAME": "First Name",
+  "SMART_FORM.PH.FIRST_NAME": "Enter your first name",
+};
+```
+
+When `labels` changes (e.g., user switches language), the form is automatically re-parsed and all labels are re-translated.
+
+### Compatibility with `labelsObject`
+
+The component also accepts the pattern used by `ConfigurableFormComponent`:
+
+```typescript
+labels = {
+  errorMaxItemsAllowed: "...",
+  labelsObject: { "SMART_FORM.TITLE": "User Registration" /* ... */ },
+};
+```
+
+If `labels.labelsObject` is present, translations are read from there; otherwise the top-level object is used directly.
+
+---
+
+## API Submission
+
+### Automatic API Submission (CREATE / POST)
+
+Configure the form to automatically submit to an API endpoint by providing a `submitConfig`. You can also provide static additional payload fields that the form will merge into the final API request.
+
+```json
+{
+  "entityType": "USER",
+  "submitConfig": {
+    "apiUrl": "https://api.example.com/users",
+    "method": "POST",
+    "successMessage": "User created successfully!",
+    "redirectUrl": "https://platformcommons.dev/home",
+    "extraPayload": {
+      "channelCode": "CHANNEL.COMMONS.GRE_DEFAULT_CHANNEL",
+      "marketCode": "COMMONS.GRE",
+      "status": {
+        "code": "REQUEST_STATUS.SUBMITTED"
+      }
+    }
+  }
+}
+```
+
+### Form Editing (EDIT / PATCH)
+
+To support editing an existing record, switch the SmartFormComponent mode to `EDIT` and provide an `editConfig` in the `FormSchema`. The component will fetch the existing data using `loadApiUrl` before the form renders, and submit changes to `submitApiUrl` using the defined `submitMethod` (default `PATCH`).
+
+```html
+<lib-smart-form [formJson]="formJson" mode="EDIT" (submit)="onSubmit($event)">
+</lib-smart-form>
+```
+
+```json
+{
+  "entityType": "USER",
+  "editConfig": {
+    "loadApiUrl": "https://api.example.com/users/123",
+    "submitApiUrl": "https://api.example.com/users/123",
+    "submitMethod": "PATCH",
+    "successMessage": "User updated successfully!",
+    "redirectUrl": "https://platformcommons.dev/home",
+    "extraPayload": {
+      "updatedBy": "admin"
+    }
+  }
+}
+```
+
+### Nested Payload Mapping
+
+By default, the form submits a flat object matching the field names. If your API requires nested structures (like `status.code` or `address.city`), specify the nested hierarchy using the `payloadPath` property on the `FieldConfig`.
+
+```json
+{
+  "name": "statusCodeInput",
+  "label": "Status",
+  "type": "TEXT_INPUT",
+  "subType": "SHORT",
+  "payloadPath": "status.code"
+}
+```
+
+Upon submission, the value from `statusCodeInput` will be formatted as:
+
+```json
+{
+  "status": {
+    "code": "Submitted value"
+  }
+}
+```
+
+**Array Support in Payload Mapping:**
+You can also specify array indices directly in the `payloadPath` if your API expects values inside nested arrays.
+
+```json
+{
+  "name": "firstName",
+  "label": "First Name",
+  "type": "TEXT_INPUT",
+  "subType": "SHORT",
+  "payloadPath": "name[0].labels.text"
+}
+```
+
+Upon submission, the value from `firstName` will be formatted as:
+
+```json
+{
+  "name": [
+    {
+      "labels": {
+        "text": "Submitted value"
+      }
+    }
+  ]
+}
+```
+
+### Deep-Merging with `extraPayload`
+
+The `SmartFormComponent` intelligently deep-merges anything you provide in `submitConfig.extraPayload` (or `editConfig.extraPayload`) with the payload constructed from the form fields.
+
+This means you can provide static extra properties that share the same nested structure (even arrays), and they will perfectly overlay each other.
+
+**Example: Merging Array Values**
+Using the `firstName` setup above, if you needed your API payload to look like this:
+
+```json
+{
+  "name": [
+    {
+      "id": 0,
+      "labels": {
+        "text": "John"
+      }
+    }
+  ]
+}
+```
+
+You simply put the static `"id": 0` inside your `extraPayload` mirroring the structure:
+
+```json
+{
+  "entityType": "USER",
+  "submitConfig": {
+    "apiUrl": "https://api.example.com/users",
+    "extraPayload": {
+      "name": [
+        {
+          "id": 0
+        }
+      ]
+    }
+  },
+  "sectionConfig": {
+    "children": [
+      {
+        "name": "firstName",
+        "payloadPath": "name[0].labels.text",
+        "type": "TEXT_INPUT"
+      }
+    ]
+  }
+}
+```
+
+The internal deep-merge algorithm combines the values at `name[0]` to produce the exact desired payload.
+
+"label": "User Registration",
+"formType": "SECTION",
+"submitConfig": {
+"apiUrl": "https://api.example.com/users",
+"method": "POST",
+"successMessage": "User created successfully",
+"errorMessage": "Failed to create user"
+},
+"sectionConfig": { "children": [...] }
+}
+
+````
+
+### Manual Submission
+
+If no `submitConfig` is provided, handle submission in the parent component via the `(submit)` output:
+
+```typescript
+onSubmit(data: any) {
+  this.http.post("https://api.example.com/users", data).subscribe(
+    response => console.log("Success", response),
+    error => console.error("Error", error)
+  );
+}
+````
+
+### Submitted Data Shape
+
+- **Flat fields** → top-level key/value pairs. If `payloadPath` is set, maps the value to the specified nested path.
+- **GROUP (Visual Section)** → If a group lacks an explicit `name` or `allowMulti`, it is purely visual. Its contents are **flattened** directly onto the target payload layer.
+- **GROUP (Structural Block)** → If a group defines `sectionConfig.name`, `field.name`, or `allowMulti: true`.
+  - Its payload is built as a nested object (or an array of objects if `allowMulti`).
+  - The object key is determined by priority: `sectionConfig.name` → `field.name` → a generated camelCase derived from `sectionConfig.label` → `__group__`.
+  - If a `payloadPath` is provided on the structural block, the payload is mapped to that precise dot-notation path instead of the generated default key.
+
+```json
+{
+  // Flattened visual group fields (no 'name' specified on the group layout)
+  "someOtherField": "Flattened value",
+  
+  // Structural single block nested under derived key
+  "basicDetails": {
+    "firstName": "John",
+    "lastName": "Doe"
+  },
+  
+  // Structural Repeater block (allowMulti: true)
+  "experienceList": [
+    { "company": "Acme", "position": "Engineer" },
+    { "company": "Globex", "position": "Lead" }
+  ]
+}
+```
+
+---
+
+## API Authentication (Token)
+
+The Smart Form can attach an auth token to **every library-initiated HTTP call** — this includes:
+
+- Dropdown / Radio / Chip option loading (`optionConfig.apiUrl`, `apiUrls`, `optionUrl`)
+- Dependent dropdown refreshes (cascading selects)
+- Automatic form submission (`submitConfig.apiUrl`)
+
+### How It Works
+
+The `token` and `tokenHeader` are defined **directly in the configJSON** (`FormSchema`). When the form is parsed, these values are stored in the `SmartFormController` service and automatically applied to every internal HTTP call — no manual `@Input` wiring in the parent template is needed.
+
+```json
+{
+  "entityType": "USER",
+  "label": "User Form",
+  "formType": "SECTION",
+  "token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "tokenHeader": "Authorization",
+  "sectionConfig": { "children": [...] }
+}
+```
+
+> **Note:** `tokenHeader` is optional. When omitted it defaults to `"Authorization"`.
+
+### Template
+
+No extra bindings are required on `<lib-smart-form>`. The token flows entirely through the JSON:
+
+```html
+<lib-smart-form
+  [formJson]="formJson"
+  [labels]="labels"
+  (submit)="onSubmit($event)"
+>
+</lib-smart-form>
+```
+
+### How the Token Flows Internally
+
+```
+FormSchema JSON
+     │  token / tokenHeader parsed by SmartFormComponent
+     ▼
+SmartFormController  (token & tokenHeader stored here)
+     │  read by every FormFieldComponent directly
+     ▼
+HttpHeaders  →  every API call (dropdowns, submit)
+```
+
+The token propagates automatically through the entire component tree without any `@Input` prop-drilling.
+
+### Per-Submit Override
+
+If your submit endpoint requires a **different** token than the option-loading endpoints, set it directly inside `submitConfig`:
+
+```json
+{
+  "submitConfig": {
+    "apiUrl": "https://api.example.com/users",
+    "method": "POST",
+    "token": "ApiKey my-write-only-key",
+    "tokenHeader": "X-API-Key"
+  }
+}
+```
+
+`submitConfig.token` always takes precedence over the schema-level `token` for the submit call only.
+
+### Priority Order
+
+```
+submitConfig.token  →  FormSchema.token  →  (no header sent)
+```
+
+---
+
+## Theme Configuration
+
+The Smart Form exposes a rich set of CSS custom properties (variables) that allow you to fully customise the appearance without touching any component SCSS.
+
+Two built-in themes are provided via a Sass mixin in `smart-form.theme.scss`.
+
+### Available Themes
+
+| Theme constant               | Description                                      |
+| ---------------------------- | ------------------------------------------------ |
+| `$default-smart-form-config` | **Theme 1** — Clean & Professional (light, blue) |
+| `$theme-2-smart-form-config` | **Theme 2** — Vibrant & Modern (dark slate)      |
+
+### Applying a Theme
+
+In your consuming application's component SCSS, `@use` the theme file and call the mixin inside a wrapper class:
+
+```scss
+@use "commons-shared-web-ui/src/lib/modules/smart-form/smart-form.theme" as sf;
+
+// Default (light) theme
+.my-form-wrapper {
+  @include sf.smart-form-theme();
+}
+
+// Dark theme
+.my-form-wrapper.dark {
+  @include sf.smart-form-theme(sf.$theme-2-smart-form-config);
+}
+```
+
+```html
+<div class="my-form-wrapper" [class.dark]="isDarkTheme">
+  <lib-smart-form [formJson]="formJson" (submit)="onSubmit($event)">
+  </lib-smart-form>
+</div>
+```
+
+### Custom Theme
+
+Pass a partial override map to `smart-form-theme()` to produce a custom theme without affecting the defaults:
+
+```scss
+@use "commons-shared-web-ui/src/lib/modules/smart-form/smart-form.theme" as sf;
+
+.my-brand-form {
+  @include sf.smart-form-theme(
+    (
+      form-bg: #f4f7ff,
+      input-focus-border: #7c3aed,
+      input-focus-shadow: 0 0 0 3px rgba(124, 58, 237, 0.2),
+      btn-primary-bg: #7c3aed,
+      btn-primary-hover-bg: #6d28d9,
+    )
+  );
+}
+```
+
+### CSS Custom Properties Reference
+
+All variables are prefixed `--cc-sf-`. They are generated by the mixin and cascade into every child component automatically.
+
+#### Form Container
+
+| Variable                     | Default (Theme 1)            | Description                     |
+| ---------------------------- | ---------------------------- | ------------------------------- |
+| `--cc-sf-font-family`        | `'Inter', sans-serif`        | Font family for the entire form |
+| `--cc-sf-font-size-base`     | `0.875rem`                   | Base font size                  |
+| `--cc-sf-form-bg`            | `#ffffff`                    | Form wrapper background         |
+| `--cc-sf-form-border-radius` | `12px`                       | Form wrapper border radius      |
+| `--cc-sf-form-border`        | `none`                       | Form wrapper border             |
+| `--cc-sf-form-shadow`        | `0 1px 3px rgba(0,0,0,0.06)` | Form wrapper box shadow         |
+| `--cc-sf-form-padding`       | `24px`                       | Form outer padding              |
+| `--cc-sf-form-max-width`     | `1200px`                     | Form max width                  |
+| `--cc-sf-form-title-color`   | `#111827`                    | Form title color                |
+| `--cc-sf-form-title-size`    | `1.5rem`                     | Form title font size            |
+| `--cc-sf-form-title-weight`  | `700`                        | Form title font weight          |
+| `--cc-sf-form-desc-color`    | `#6B7280`                    | Form description color          |
+| `--cc-sf-form-desc-size`     | `0.875rem`                   | Form description font size      |
+
+#### Section / GROUP Card
+
+| Variable                       | Default (Theme 1)   | Description                   |
+| ------------------------------ | ------------------- | ----------------------------- |
+| `--cc-sf-section-bg`           | `#ffffff`           | Section card background       |
+| `--cc-sf-section-border`       | `1px solid #E5E7EB` | Section card border           |
+| `--cc-sf-section-radius`       | `10px`              | Section card border radius    |
+| `--cc-sf-section-shadow`       | `0 1px 4px rgba(…)` | Section card box shadow       |
+| `--cc-sf-section-padding`      | `20px`              | Section card inner padding    |
+| `--cc-sf-section-gap`          | `20px`              | Gap between sections          |
+| `--cc-sf-section-label-color`  | `#1F2937`           | Section heading color         |
+| `--cc-sf-section-label-size`   | `1rem`              | Section heading font size     |
+| `--cc-sf-section-label-weight` | `600`               | Section heading font weight   |
+| `--cc-sf-section-label-border` | `2px solid #E5E7EB` | Section heading bottom border |
+
+#### Grid
+
+| Variable               | Default (Theme 1) | Description                        |
+| ---------------------- | ----------------- | ---------------------------------- |
+| `--cc-sf-grid-gap`     | `16px`            | Gap between columns in all grids   |
+| `--cc-sf-grid-row-gap` | `12px`            | Gap between rows in section grid   |
+
+#### Labels
+
+| Variable                       | Default (Theme 1) | Description                        |
+| ------------------------------ | ----------------- | ---------------------------------- |
+| `--cc-sf-label-color`          | `#111827`         | Field label text color             |
+| `--cc-sf-label-size`           | `0.875rem`        | Field label font size              |
+| `--cc-sf-label-weight`         | `500`             | Field label font weight            |
+| `--cc-sf-label-required-color` | `#DC2626`         | Required asterisk color            |
+| `--cc-sf-label-mb`             | `0px`             | Field label bottom margin offset   |
+
+#### Inputs
+
+| Variable                        | Default (Theme 1)                 | Description               |
+| ------------------------------- | --------------------------------- | ------------------------- |
+| `--cc-sf-input-bg`              | `#ffffff`                         | Input background          |
+| `--cc-sf-input-color`           | `#111827`                         | Input text color          |
+| `--cc-sf-input-placeholder`     | `#9CA3AF`                         | Placeholder text color    |
+| `--cc-sf-input-border`          | `1.5px solid #D1D5DB`             | Input border              |
+| `--cc-sf-input-radius`          | `8px`                             | Input border radius       |
+| `--cc-sf-input-padding`         | `0.625rem 0.875rem`               | Input padding             |
+| `--cc-sf-input-shadow`          | `none`                            | Input default box shadow  |
+| `--cc-sf-input-hover-border`    | `#9CA3AF`                         | Input border on hover     |
+| `--cc-sf-input-focus-border`    | `#3B82F6`                         | Input border when focused |
+| `--cc-sf-input-focus-shadow`    | `0 0 0 3px rgba(59,130,246,0.12)` | Focus ring glow           |
+| `--cc-sf-input-disabled-bg`     | `#F3F4F6`                         | Disabled input background |
+| `--cc-sf-input-disabled-color`  | `#6B7280`                         | Disabled input text color |
+| `--cc-sf-input-disabled-border` | `#E5E7EB`                         | Disabled input border     |
+| `--cc-sf-input-transition`      | `all 0.2s ease`                   | Input transition speed    |
+
+#### Validation
+
+| Variable                     | Default (Theme 1)               | Description                    |
+| ---------------------------- | ------------------------------- | ------------------------------ |
+| `--cc-sf-error-border`       | `#DC2626`                       | Error state input border color |
+| `--cc-sf-error-bg`           | `#FEF2F2`                       | Error state input background   |
+| `--cc-sf-error-focus-shadow` | `0 0 0 3px rgba(220,38,38,0.1)` | Error state focus ring         |
+| `--cc-sf-error-text-color`   | `#DC2626`                       | Error message text color       |
+| `--cc-sf-error-text-size`    | `0.75rem`                       | Error message font size        |
+| `--cc-sf-hint-color`         | `#6B7280`                       | Hint text color                |
+| `--cc-sf-hint-size`          | `0.75rem`                       | Hint text font size            |
+
+#### Chips
+
+| Variable                       | Default (Theme 1)   | Description              |
+| ------------------------------ | ------------------- | ------------------------ |
+| `--cc-sf-chip-bg`              | `#ffffff`           | Chip default background  |
+| `--cc-sf-chip-color`           | `#374151`           | Chip default text color  |
+| `--cc-sf-chip-border`          | `1px solid #D1D5DB` | Chip border              |
+| `--cc-sf-chip-radius`          | `20px`              | Chip border radius       |
+| `--cc-sf-chip-padding`         | `6px 14px`          | Chip padding             |
+| `--cc-sf-chip-hover-bg`        | `#F3F4F6`           | Chip hover background    |
+| `--cc-sf-chip-selected-bg`     | `#3B82F6`           | Selected chip background |
+| `--cc-sf-chip-selected-color`  | `#ffffff`           | Selected chip text       |
+| `--cc-sf-chip-selected-border` | `#3B82F6`           | Selected chip border     |
+
+#### Switch
+
+| Variable                   | Default (Theme 1) | Description         |
+| -------------------------- | ----------------- | ------------------- |
+| `--cc-sf-switch-track-on`  | `#3B82F6`         | Toggle track (on)   |
+| `--cc-sf-switch-track-off` | `#D1D5DB`         | Toggle track (off)  |
+| `--cc-sf-switch-thumb`     | `#ffffff`         | Toggle thumb colour |
+
+#### Rating Stars
+
+| Variable              | Default (Theme 1) | Description        |
+| --------------------- | ----------------- | ------------------ |
+| `--cc-sf-star-filled` | `#F59E0B`         | Filled star colour |
+| `--cc-sf-star-empty`  | `#D1D5DB`         | Empty star colour  |
+| `--cc-sf-star-size`   | `28px`            | Star font size     |
+
+#### File Upload Drop Zone
+
+| Variable                        | Default (Theme 1)      | Description                  |
+| ------------------------------- | ---------------------- | ---------------------------- |
+| `--cc-sf-dropzone-bg`           | `#FFFAF1`              | Drop zone background         |
+| `--cc-sf-dropzone-border`       | `1.5px dashed #CBD5E1` | Drop zone border             |
+| `--cc-sf-dropzone-radius`       | `12px`                 | Drop zone border radius      |
+| `--cc-sf-dropzone-hover-bg`     | `#EFF6FF`              | Hover background             |
+| `--cc-sf-dropzone-hover-border` | `#93C5FD`              | Hover border                 |
+| `--cc-sf-dropzone-over-border`  | `#3B82F6`              | Active drag-over border      |
+| `--cc-sf-dropzone-icon-color`   | `#94A3B8`              | Cloud icon colour            |
+| `--cc-sf-dropzone-link-color`   | `#3B82F6`              | "click to upload" link color |
+| `--cc-sf-dropzone-hint-color`   | `#64748B`              | Hint text colour in zone     |
+| `--cc-sf-dropzone-over-shadow`  | `0 0 0 4px rgba(…)`    | Drag-over glow               |
+
+#### Stepper
+
+| Variable                           | Default (Theme 1) | Description                      |
+| ---------------------------------- | ----------------- | -------------------------------- |
+| `--cc-sf-step-number-size`         | `40px`            | Step bubble size                 |
+| `--cc-sf-step-number-bg`           | `#E5E7EB`         | Idle step bubble background      |
+| `--cc-sf-step-number-color`        | `#6B7280`         | Idle step number colour          |
+| `--cc-sf-step-number-font-size`    | `0.875rem`        | Step number font size            |
+| `--cc-sf-step-number-weight`       | `600`             | Step number font weight          |
+| `--cc-sf-step-label-color`         | `#6B7280`         | Idle step label colour           |
+| `--cc-sf-step-label-size`          | `0.875rem`        | Step label font size             |
+| `--cc-sf-step-label-weight`        | `500`             | Step label font weight           |
+| `--cc-sf-step-active-bg`           | `#3B82F6`         | Active step bubble background    |
+| `--cc-sf-step-active-color`        | `#ffffff`         | Active step number colour        |
+| `--cc-sf-step-active-label`        | `#1D4ED8`         | Active step label colour         |
+| `--cc-sf-step-active-label-weight` | `700`             | Active step label font weight    |
+| `--cc-sf-step-done-bg`             | `#22C55E`         | Completed step bubble background |
+| `--cc-sf-step-done-color`          | `#ffffff`         | Completed step number colour     |
+| `--cc-sf-step-connector-color`     | `#E5E7EB`         | Connector line (idle)            |
+| `--cc-sf-step-connector-done`      | `#22C55E`         | Connector line (completed)       |
+
+#### Action Buttons
+
+| Variable                         | Default (Theme 1)    | Description                        |
+| -------------------------------- | -------------------- | ---------------------------------- |
+| `--cc-sf-btn-primary-bg`         | `#3B82F6`            | Primary (submit) button background |
+| `--cc-sf-btn-primary-color`      | `#ffffff`            | Primary button text colour         |
+| `--cc-sf-btn-primary-radius`     | `8px`                | Primary button border radius       |
+| `--cc-sf-btn-primary-padding`    | `0.625rem 1.5rem`    | Primary button padding             |
+| `--cc-sf-btn-primary-hover-bg`   | `#2563EB`            | Primary button hover background    |
+| `--cc-sf-btn-secondary-bg`       | `#F3F4F6`            | Secondary (previous) button bg     |
+| `--cc-sf-btn-secondary-color`    | `#374151`            | Secondary button text colour       |
+| `--cc-sf-btn-secondary-radius`   | `8px`                | Secondary button border radius     |
+| `--cc-sf-btn-secondary-padding`  | `0.625rem 1.5rem`    | Secondary button padding           |
+| `--cc-sf-btn-secondary-hover-bg` | `#E5E7EB`            | Secondary button hover background  |
+| `--cc-sf-btn-disabled-opacity`   | `0.55`               | Disabled button opacity            |
+| `--cc-sf-btn-font-size`          | `0.875rem`           | Button font size                   |
+| `--cc-sf-btn-font-weight`        | `600`                | Button font weight                 |
+| `--cc-sf-btn-transition`         | `all 0.2s ease`      | Button transition                  |
+| `--cc-sf-actions-gap`            | `12px`               | Gap between action buttons         |
+| `--cc-sf-actions-padding`        | `20px 0 0`           | Action bar padding                 |
+| `--cc-sf-actions-border`         | `1px solid #E5E7EB`  | Action bar top border              |
+| `--cc-sf-btn-add-bg`             | `transparent`        | Add-instance button background     |
+| `--cc-sf-btn-add-color`          | `#3B82F6`            | Add-instance button text colour    |
+| `--cc-sf-btn-add-border`         | `1px dashed #CBD5E1` | Add-instance button border         |
+| `--cc-sf-btn-add-radius`         | `6px`                | Add-instance button radius         |
+| `--cc-sf-btn-add-hover-bg`       | `#EFF6FF`            | Add-instance button hover bg       |
+| `--cc-sf-btn-add-hover-border`   | `#BFDBFE`            | Add-instance button hover border   |
+| `--cc-sf-btn-remove-bg`          | `#FFF5F5`            | Remove-instance button background  |
+| `--cc-sf-btn-remove-color`       | `#E53E3E`            | Remove-instance button text colour |
+| `--cc-sf-btn-remove-border`      | `1px solid #FED7D7`  | Remove-instance button border      |
+| `--cc-sf-btn-remove-radius`      | `4px`                | Remove-instance button radius      |
+| `--cc-sf-btn-remove-hover-bg`    | `#FED7D7`            | Remove-instance button hover bg    |
+
+---
+
+## Examples
+
+### Contact Form
+
+```json
+{
+"entityType": "CONTACT",
+"label": "Contact Us",
+"formType": "SECTION",
+"submitConfig": {
+"apiUrl": "https://api.example.com/contact",
+"method": "POST",
+"successMessage": "Message sent successfully",
+"errorMessage": "Failed to send message",
+"snackbarConfig": {
+"duration": 6000,
+"verticalPosition": "top",
+"horizontalPosition": "center",
+"showCloseButton": true
+}
+},
+"sectionConfig": {
+"children": [
+{
+"name": "name",
+"label": "Full Name",
+"type": "TEXT_INPUT",
+"subType": "SHORT",
+"required": true
+},
+{
+"name": "email",
+"label": "Email Address",
+"type": "TEXT_INPUT",
+"subType": "EMAIL",
+"required": true
+},
+{
+"name": "message",
+"label": "Message",
+"type": "TEXT_INPUT",
+"subType": "LONG",
+"required": true,
+"textConfig": { "length": { "min": 10, "max": 500 } }
+}
+]
+}
+}
+```
+
+### User Registration with Password Validation
+
+```json
+{
+  "entityType": "USER_REGISTRATION",
+  "label": "User Registration",
+  "formType": "SECTION",
+  "sectionConfig": {
+    "children": [
+      {
+        "type": "GROUP",
+        "subType": "SECTION",
+        "sectionConfig": {
+          "label": "Credentials",
+          "name": "credentials",
+          "children": [
+            {
+              "type": "ROW",
+              "subType": "HORIZONTAL",
+              "children": [
+                {
+                  "name": "loginId",
+                  "label": "Login ID",
+                  "type": "TEXT_INPUT",
+                  "subType": "SHORT",
+                  "required": true,
+                  "colSpan": 4
+                },
+                {
+                  "name": "password",
+                  "label": "Password",
+                  "type": "TEXT_INPUT",
+                  "subType": "PASSWORD",
+                  "required": true,
+                  "colSpan": 4
+                },
+                {
+                  "name": "confirmPassword",
+                  "label": "Confirm Password",
+                  "type": "TEXT_INPUT",
+                  "subType": "PASSWORD",
+                  "required": true,
+                  "colSpan": 4,
+                  "textConfig": { "matchField": "password" }
+                }
+              ]
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+### Section Stepper with `showOnLastStepOnly`
+
+A three-step registration form using Section Stepper. The **Submit** button carries `"showOnLastStepOnly": true` so it is only visible on the last step. **Previous** and **Next** are rendered automatically by the form — no extra config needed.
+
+```json
+{
+  "entityType": "REGISTRATION",
+  "label": "Event Registration",
+  "formType": "SECTION",
+  "sectionStepper": true,
+  "submitConfig": {
+    "apiUrl": "https://api.example.com/registrations",
+    "method": "POST",
+    "successMessage": "Registration submitted successfully!",
+    "redirectUrl": "/dashboard"
+  },
+  "actionBarConfig": {
+    "buttons": [
+      {
+        "id": "cancel",
+        "label": "Cancel",
+        "variant": "outline",
+        "alignment": "left",
+        "order": 0,
+        "action": { "kind": "navigate", "redirectUrl": "/dashboard" }
+      },
+      {
+        "id": "save-draft",
+        "label": "Save as Draft",
+        "variant": "secondary",
+        "alignment": "right",
+        "order": 0,
+        "action": { "kind": "draft", "extraPayload": { "status": "DRAFT" } }
+      },
+      {
+        "id": "submit",
+        "label": "Submit",
+        "variant": "primary",
+        "alignment": "right",
+        "order": 1,
+        "showOnLastStepOnly": true,
+        "action": { "kind": "submit" }
+      }
+    ]
+  },
+  "sectionConfig": {
+    "children": [
+      {
+        "type": "GROUP",
+        "subType": "SECTION",
+        "sectionConfig": {
+          "label": "Personal Info",
+          "children": [
+            {
+              "type": "ROW",
+              "subType": "HORIZONTAL",
+              "children": [
+                {
+                  "name": "firstName",
+                  "label": "First Name",
+                  "type": "TEXT_INPUT",
+                  "subType": "SHORT",
+                  "required": true,
+                  "colSpan": 6
+                },
+                {
+                  "name": "lastName",
+                  "label": "Last Name",
+                  "type": "TEXT_INPUT",
+                  "subType": "SHORT",
+                  "required": true,
+                  "colSpan": 6
+                }
+              ]
+            },
+            {
+              "name": "email",
+              "label": "Email Address",
+              "type": "TEXT_INPUT",
+              "subType": "EMAIL",
+              "required": true
+            }
+          ]
+        }
+      },
+      {
+        "type": "GROUP",
+        "subType": "SECTION",
+        "sectionConfig": {
+          "label": "Event Preferences",
+          "children": [
+            {
+              "name": "session",
+              "label": "Preferred Session",
+              "type": "DROPDOWN",
+              "subType": "SINGLE",
+              "required": true,
+              "optionConfig": {
+                "optionList": [
+                  { "label": "Morning", "code": "MORNING" },
+                  { "label": "Afternoon", "code": "AFTERNOON" },
+                  { "label": "Evening", "code": "EVENING" }
+                ]
+              }
+            },
+            {
+              "name": "dietaryRequirements",
+              "label": "Dietary Requirements",
+              "type": "CHIP",
+              "subType": "MULTIPLE",
+              "optionConfig": {
+                "optionList": [
+                  { "label": "Vegetarian", "code": "VEG" },
+                  { "label": "Vegan", "code": "VEGAN" },
+                  { "label": "Gluten-Free", "code": "GF" },
+                  { "label": "None", "code": "NONE" }
+                ]
+              }
+            }
+          ]
+        }
+      },
+      {
+        "type": "GROUP",
+        "subType": "SECTION",
+        "sectionConfig": {
+          "label": "Review & Submit",
+          "children": [
+            {
+              "name": "agreeToTerms",
+              "label": "I agree to the terms and conditions",
+              "type": "CHECKBOX",
+              "subType": "BOOL",
+              "required": true
+            },
+            {
+              "name": "notes",
+              "label": "Additional Notes",
+              "type": "TEXT_INPUT",
+              "subType": "LONG"
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+**What the action bar looks like on each step:**
+
+| Step | Left side | Right side |
+|------|-----------|------------|
+| Step 1 (first) | Cancel | Save as Draft · **Next** |
+| Step 2 | Cancel · **Previous** | Save as Draft · **Next** |
+| Step 3 (last) | Cancel · **Previous** | Save as Draft · **Submit** |
+
+- **Previous** / **Next** are rendered automatically; no button config needed.
+- **Submit** (`showOnLastStepOnly: true`) is hidden on steps 1 and 2, then replaces **Next** on step 3.
+- **Cancel** and **Save as Draft** have no `showOnLastStepOnly` flag, so they appear on every step.
+
+### Repeatable Work Experience
+
+```json
+{
+  "type": "GROUP",
+  "subType": "SECTION",
+  "sectionConfig": {
+    "label": "Work Experience",
+    "allowMulti": true,
+    "name": "experienceList",
+    "children": [
+      {
+        "name": "company",
+        "label": "Company",
+        "type": "TEXT_INPUT",
+        "subType": "SHORT",
+        "required": true
+      },
+      {
+        "name": "position",
+        "label": "Position",
+        "type": "TEXT_INPUT",
+        "subType": "SHORT",
+        "required": true
+      },
+      {
+        "type": "ROW",
+        "subType": "HORIZONTAL",
+        "children": [
+          {
+            "name": "startDate",
+            "label": "Start Date",
+            "type": "DATE",
+            "subType": "SINGLE",
+            "required": true,
+            "colSpan": 6
+          },
+          {
+            "name": "endDate",
+            "label": "End Date",
+            "type": "DATE",
+            "subType": "SINGLE",
+            "colSpan": 6
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## API Reference
+
+### Component Inputs
+
+| Input                 | Type    | Required | Description                                                                                                                         |
+| --------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `formJson`            | string  | Yes      | JSON string of the form schema configuration                                                                                        |
+| `mode`                | string  | No       | Determines whether the form creates or edits an entity: `"CREATE" \| "EDIT"` (default: `"CREATE"`)                                  |
+| `initialValues`       | object  | No       | Pre-populate form values (key = field `name`)                                                                                       |
+| `enableDraftAutoSave` | boolean | No       | Enable auto-save drafts (default: `false`)                                                                                          |
+| `labels`              | object  | No       | Flat i18n key–value map. Keys must match the string values used in the JSON schema. See [i18n section](#i18n--translation-support). |
+| `readOnly`            | boolean | No       | When `true`, all form controls are disabled and the action bar is hidden. Use this for **read-only preview** in a Form Builder wizard (default: `false`). |
+
+
+### Component Outputs
+
+| `submit`            | `EventEmitter<object>`                                  | Emitted when the form is submitted. Contains collected form data or the API response |
+| `draftSave`         | `EventEmitter<string>`                                  | Emitted when a draft is saved (requires `enableDraftAutoSave: true`)                 |
+| `fileAdded`         | `EventEmitter<any>`                                     | Emitted when a file upload starts internally (MEDIA_UPLOAD or FILE_UPLOAD).         |
+| `fileRemoved`       | `EventEmitter<any>`                                     | Emitted when a file upload completes, fails, or is manually removed.                |
+| `suffixActionClick` | `EventEmitter<{ fieldName: string; actionId: string }>` | Emitted when a clickable action icon (configured via `suffixActionIcons`) is clicked inside a text or number field. |
+
+### Usage in Component
+
+```typescript
+@Component({
+  template: `
+    <lib-smart-form
+      [formJson]="formJson"
+      [initialValues]="initialData"
+      [labels]="labels"
+      (submit)="handleSubmit($event)"
+    >
+    </lib-smart-form>
+  `,
+})
+export class MyComponent {
+  formJson: string; // JSON.stringify(yourSchemaObject)
+  initialData = { firstName: "John" };
+  labels = { "FIELD.FIRST_NAME": "First Name" };
+
+  handleSubmit(data: any) {
+    console.log("Form Data:", data);
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. Use **meaningful camelCase field names** (`firstName`, `emailId`).
+2. Store all label strings in your **i18n JSON files** and pass them via `[labels]`. Every label property in the JSON schema should be an i18n key that exists in your translation files. These are processed by `SmartFormTranslationUtils` before rendering.
+3. Always set `name` on `GROUP` + `allowMulti` sections — it becomes the `FormArray` key.
+4. Use `colSpan` to build responsive multi-column layouts inside `ROW`.
+5. Use `visibilityExpression` to keep forms concise — hidden fields are excluded from submission.
+6. Provide `hints` and `placeholders` for complex fields; these are also translatable.
+7. Use `matchField` for confirm-password style validation instead of custom validators.
+8. Test `GENERATED` formulas with `null`/`undefined` inputs — they will be called before the user types.
+9. For long forms, prefer `STEPPER` over a single `SECTION` with many fields.
+10. Verify `submitConfig.apiUrl` CORS settings before relying on automatic API submission.
+11. Always set **`token`** in the configJSON (`FormSchema.token`) when dropdowns load from secured API endpoints — without it the requests will be unauthenticated. The token flows automatically to every field; no `@Input` binding is needed on `<lib-smart-form>`.
+12. Apply themes using the `smart-form-theme()` mixin inside a scoped wrapper class, not at `:root` level, to avoid conflicts with other form instances on the same page.
+13. Structure non-repeater section fields directly under `sectionConfig.children` using `colSpan` (`12`, `6`, `4`) rather than wrapping non-repeater fields in unnecessary `ROW` or `GROUP` wrappers. This allows the 12-column `sf-grid` to handle layout automatically and supports field-level collapsing in configurators.
+
+---
+
+## Troubleshooting
+
+### Form not rendering
+
+- Ensure `formJson` is a valid JSON **string** (use `JSON.stringify`).
+- Check the browser console for parse errors.
+
+### Labels not translating
+
+- Confirm the key in `labels` exactly matches the string value in the schema JSON.
+- If `labels` arrives after `formJson`, the component automatically re-parses — but make sure `ngOnChanges` is reaching the component (i.e., `labels` is a fresh object reference, not mutated in place).
+
+### Repeater instances sharing values
+
+- Ensure `sectionConfig.name` is set on the `GROUP` field — without it the `FormArray` key defaults to `__repeater__` and may conflict.
+- Each repeater instance starts blank by design (`inRepeater: true` disables cross-instance controller reads).
+
+### Generated fields not updating
+
+- Verify `variables` lists every field name the formula reads.
+- Check formula syntax — it must be a valid **named** JavaScript function.
+
+### API submission not working
+
+- Verify `submitConfig.apiUrl` is correct and the server allows the HTTP method.
+- Check CORS settings on the API endpoint.
+
+### Dropdown options not loading
+
+- Verify `apiUrl` / `optionUrl` is reachable.
+- Check `dataPath` if the response wraps the array in an object.
+- Verify `labelPath` and `valuePath` exist on each item.
+- For dependent dropdowns, ensure the parent field name in `dependencies` maps matches the field's `name` exactly.
+
+### Dropdown options return 401 / 403
+
+- Set `token` and optionally `tokenHeader` inside the **configJSON** (`FormSchema`) so the library attaches auth headers to every dropdown API call automatically.
+- If only the **submit** endpoint is secured, set `token` inside `submitConfig` in the JSON schema — it takes precedence over `FormSchema.token` for the submit call only.
+- Confirm the token value includes the scheme prefix if required by your API (e.g. `"Bearer "` not just the raw JWT).
+
+---
+
+## License
+
+This module is part of the shared-ui library.