platformcommons-web-lib 1.0.0

package/documentation/smart-form.md

@@ -0,0 +1,2177 @@
+# 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 and there are more than one — set `"sectionStepper": false` to suppress auto-detection.
+
+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 and there are more than one |
+
+---
+
+## 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"
+  }
+}
+```
+
+### 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`. |
+
+**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"
+  }
+}
+```
+
+### 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"
+  }
+}
+```
+
+### 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. 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"
+  }
+}
+```
+
+---
+
+## 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
+}
+```
+
+---
+
+## 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": "..." }, ...] }`.
+
+### 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) can be localized by providing the corresponding 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"
+  }
+}
+```
+
+If a mapping is not provided in `labels`, the buttons will fall back to default English strings ("Next", "Submit", etc.).
+
+### 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)        |
+
+> **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 |
+
+#### 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 |
+
+#### 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
+
+{
+"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.
+
+---
+
+## 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.