platformcommons-web-lib 1.0.0

package/documentation/configurable-form.md

@@ -0,0 +1,605 @@
+# Configurable Form Component Documentation
+
+The `ConfigurableFormComponent` is a powerful, dynamic form builder that supports JSON-based configuration, dependent dropdowns, repeater sections, composite fields, and comprehensive validation.
+
+## Features
+
+- **JSON-Based Configuration**: Build complex forms from JSON configuration
+- **Dependent Dropdowns**: Cascading dropdowns with automatic value clearing
+- **Repeater Sections**: Add/remove multiple items dynamically with min/max validation
+- **Composite Fields**: Group related fields (e.g., Age Range: Min - Max)
+- **Rich Field Types**: Text, Number, Email, Tel, Date, Dropdown, Radio, File Upload, Textarea
+- **API Integration**: Load dropdown options from REST APIs with dynamic URL substitution
+- **Comprehensive Validation**: Required, min/max length, pattern matching, custom validators
+- **Mobile Responsive**: Bootstrap-like grid system (col-6, col-md-4, etc.)
+- **File Upload**: Single/multiple file upload with preview and size validation
+- **Character Count**: Real-time character counting for text fields
+- **Help Text**: Contextual help text for fields
+- **Collapsible Sections**: Organize forms with collapsible sections
+
+## 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
+```
+
+Import the `ConfigurableFormModule` into your feature module or `SharedModule`.
+
+```typescript
+import { ConfigurableFormModule } from "@campus-cloud/shared-ui";
+
+@NgModule({
+  imports: [
+    ConfigurableFormModule,
+    // ...
+  ],
+})
+export class MyFeatureModule {}
+```
+
+## API Reference
+
+### Inputs
+
+| Input        | Type             | Default  | Description                                 |
+| ------------ | ---------------- | -------- | ------------------------------------------- |
+| `config`     | `FormConfig`     | required | Form configuration object (standard format) |
+| `jsonConfig` | `JsonFormConfig` | optional | JSON-based configuration from API           |
+| `data`       | `any`            | `{}`     | Initial form data for pre-filling           |
+| `baseApiUrl` | `string`         | `''`     | Base URL for API calls (dropdown options)   |
+
+### Outputs
+
+| Output       | Type                 | Description                                    |
+| ------------ | -------------------- | ---------------------------------------------- |
+| `formSubmit` | `EventEmitter<any>`  | Emitted when form is submitted with valid data |
+| `formCancel` | `EventEmitter<void>` | Emitted when cancel button is clicked          |
+
+## Configuration Interfaces
+
+### FormConfig
+
+```typescript
+interface FormConfig {
+  sections: FormSection[];
+  submitLabel?: string; // Default: 'Submit'
+  cancelLabel?: string; // Default: 'Cancel'
+  saveDraftLabel?: string; // Default: 'Save Draft'
+  isModal?: boolean; // Default: false
+  entityType?: string;
+}
+```
+
+### FormSection
+
+```typescript
+interface FormSection {
+  sectionTitle?: string;
+  fields: FormField[];
+  isRepeater?: boolean; // Enable repeater functionality
+  formArrayName?: string; // Name for FormArray (default: 'items')
+  repeaterItemLabel?: string; // Label for items (e.g., 'Contact')
+  addLabel?: string; // 'Add More' button text
+  minItems?: number; // Minimum items (default: 1)
+  maxItems?: number; // Maximum items
+  collapsible?: boolean; // Can section be collapsed
+  collapsed?: boolean; // Initial collapsed state
+  noCardLayout?: boolean; // Remove card styling
+}
+```
+
+### FormField
+
+```typescript
+interface FormField {
+  name: string; // Field name (required)
+  jsonKey?: string; // JSON key for API mapping
+  label: string; // Field label (required)
+  type: FieldType; // Field type
+  placeholder?: string; // Placeholder text
+  required?: boolean; // Is field required
+  mandatory?: boolean; // Is field mandatory
+  disabled?: boolean; // Is field disabled
+  visible?: boolean; // Is field visible
+  class?: string; // Grid class (e.g., 'col-6 col-md-4')
+  value?: any; // Initial value
+
+  // Options
+  options?: FormOption[]; // Static options array
+  optionConfigs?: OptionConfig; // API configuration for options
+  loadedOptions?: FormOption[]; // Loaded options from API
+
+  // Dependencies
+  dependsOn?: string; // Parent field name
+  dependent?: string[]; // Array of child field names
+
+  // Validation
+  validationRules?: ValidationRules;
+
+  // Composite Fields
+  type?: "composite";
+  subFields?: FormField[]; // Sub-fields for composite
+  compositeValidationRule?: "minMax" | "percentageTotal";
+
+  // File Upload
+  multiple?: boolean; // Allow multiple files
+  uploadedFiles?: any[]; // Uploaded files array
+
+  // UI Config
+  uiConfig?: UIConfig;
+  helpText?: string; // Help text below field
+
+  // Styling
+  valueColor?: string;
+  headerColor?: string;
+}
+```
+
+### FieldType
+
+```typescript
+type FieldType =
+  | "text"
+  | "number"
+  | "email"
+  | "tel"
+  | "password"
+  | "url"
+  | "textarea"
+  | "dropdown"
+  | "select"
+  | "radio"
+  | "date"
+  | "file"
+  | "composite";
+```
+
+### ValidationRules
+
+```typescript
+interface ValidationRules {
+  isMandatory?: boolean;
+  isRequired?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  min?: number;
+  max?: number;
+  pattern?: string; // Regex pattern
+}
+```
+
+### OptionConfig (for API-based dropdowns)
+
+```typescript
+interface OptionConfig {
+  optionDTO: "OPTION_DTO.STATIC" | "OPTION_DTO.REF_DATA";
+  staticOptions?: FormOption[];
+  url?: string; // API endpoint
+  labelKey?: string; // Key for label in response (default: 'name')
+  valueKey?: string; // Key for value in response (default: 'id')
+  requestKey?: string; // Key for request parameter (default: 'code')
+}
+```
+
+## Usage Examples
+
+### Basic Form
+
+```typescript
+import { ConfigurableFormModule } from "shared-ui";
+
+formConfig: FormConfig = {
+  sections: [
+    {
+      sectionTitle: "Personal Information",
+      fields: [
+        {
+          name: "firstName",
+          label: "First Name",
+          type: "text",
+          required: true,
+          class: "col-6",
+        },
+        {
+          name: "lastName",
+          label: "Last Name",
+          type: "text",
+          required: true,
+          class: "col-6",
+        },
+        {
+          name: "email",
+          label: "Email",
+          type: "email",
+          required: true,
+          class: "col-12",
+        },
+      ],
+    },
+  ],
+};
+```
+
+```html
+<lib-configurable-form
+  [config]="formConfig"
+  (formSubmit)="onSubmit($event)"
+  (formCancel)="onCancel()"
+>
+</lib-configurable-form>
+```
+
+### Dependent Dropdowns (Cascading)
+
+```typescript
+formConfig: FormConfig = {
+  sections: [
+    {
+      sectionTitle: "Location",
+      fields: [
+        {
+          name: "state",
+          label: "State",
+          type: "dropdown",
+          required: true,
+          dependent: ["district"], // Will clear district when state changes
+          optionConfigs: {
+            optionDTO: "OPTION_DTO.REF_DATA",
+            url: "api/states",
+            labelKey: "name",
+            valueKey: "code",
+          },
+        },
+        {
+          name: "district",
+          label: "District",
+          type: "dropdown",
+          required: true,
+          dependsOn: "state",
+          dependent: ["taluk"],
+          optionConfigs: {
+            optionDTO: "OPTION_DTO.REF_DATA",
+            url: "api/districts?stateCode={state}", // {state} will be replaced
+            labelKey: "name",
+            valueKey: "code",
+          },
+        },
+        {
+          name: "taluk",
+          label: "Taluk",
+          type: "dropdown",
+          required: true,
+          dependsOn: "district",
+          optionConfigs: {
+            optionDTO: "OPTION_DTO.REF_DATA",
+            url: "api/taluks?districtCode={district}",
+            labelKey: "name",
+            valueKey: "code",
+          },
+        },
+      ],
+    },
+  ],
+};
+```
+
+### Repeater Section (Dynamic Add/Remove)
+
+```typescript
+formConfig: FormConfig = {
+  sections: [
+    {
+      sectionTitle: "Contact Information",
+      isRepeater: true,
+      formArrayName: "contacts",
+      repeaterItemLabel: "Contact",
+      addLabel: "Add Another Contact",
+      minItems: 1,
+      maxItems: 5,
+      fields: [
+        {
+          name: "contactName",
+          label: "Contact Name",
+          type: "text",
+          required: true,
+          class: "col-6",
+        },
+        {
+          name: "contactPhone",
+          label: "Phone Number",
+          type: "tel",
+          required: true,
+          class: "col-6",
+        },
+        {
+          name: "contactEmail",
+          label: "Email",
+          type: "email",
+          class: "col-12",
+        },
+      ],
+    },
+  ],
+};
+```
+
+### Composite Fields (Min-Max, Percentages)
+
+```typescript
+formConfig: FormConfig = {
+  sections: [
+    {
+      sectionTitle: "Target Demographics",
+      fields: [
+        {
+          name: "targetAge",
+          label: "Target Age Group",
+          type: "composite",
+          compositeValidationRule: "minMax",
+          required: true,
+          subFields: [
+            {
+              name: "minAge",
+              label: "Min Age",
+              type: "number",
+              class: "col-6",
+            },
+            {
+              name: "maxAge",
+              label: "Max Age",
+              type: "number",
+              class: "col-6",
+            },
+          ],
+        },
+        {
+          name: "genderSplit",
+          label: "Gender Split (%)",
+          type: "composite",
+          compositeValidationRule: "percentageTotal", // Must add up to 100
+          required: true,
+          subFields: [
+            {
+              name: "malePercentage",
+              label: "Male %",
+              type: "number",
+              class: "col-6",
+            },
+            {
+              name: "femalePercentage",
+              label: "Female %",
+              type: "number",
+              class: "col-6",
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+```
+
+### File Upload with Preview
+
+```typescript
+formConfig: FormConfig = {
+  sections: [
+    {
+      sectionTitle: "Documents",
+      fields: [
+        {
+          name: "profilePhoto",
+          label: "Profile Photo",
+          type: "file",
+          required: true,
+          multiple: false,
+          helpText: "Upload a photo (max 5MB)",
+          class: "col-6",
+        },
+        {
+          name: "documents",
+          label: "Supporting Documents",
+          type: "file",
+          multiple: true,
+          helpText: "Upload multiple documents (max 5MB each)",
+          class: "col-6",
+        },
+      ],
+    },
+  ],
+};
+```
+
+### Static Dropdown Options
+
+```typescript
+formConfig: FormConfig = {
+  sections: [
+    {
+      fields: [
+        {
+          name: "gender",
+          label: "Gender",
+          type: "dropdown",
+          required: true,
+          optionConfigs: {
+            optionDTO: "OPTION_DTO.STATIC",
+            staticOptions: [
+              { label: "Male", value: "M" },
+              { label: "Female", value: "F" },
+              { label: "Other", value: "O" },
+            ],
+          },
+        },
+      ],
+    },
+  ],
+};
+```
+
+### With Character Limit and Help Text
+
+```typescript
+formConfig: FormConfig = {
+  sections: [
+    {
+      fields: [
+        {
+          name: "description",
+          label: "Project Description",
+          type: "textarea",
+          required: true,
+          validationRules: {
+            maxLength: 500,
+          },
+          helpText: "Provide a brief description of your project",
+          class: "col-12",
+        },
+      ],
+    },
+  ],
+};
+```
+
+### Using JSON Config from API
+
+```typescript
+// When receiving configuration from backend API
+jsonConfig: JsonFormConfig = {
+  label: "Village Registration",
+  entityType: "VILLAGE",
+  jsonConfig: [
+    {
+      jsonKey: "villageName",
+      label: "Village Name",
+      sequence: 1,
+      keyType: "STRING",
+      uiConfig: {
+        type: "UI_TYPE.TEXT_BOX",
+        subType: "UI_SUBTYPE.SHORT_TEXT",
+      },
+      validationRules: {
+        isMandatory: true,
+        maxLength: 100,
+      },
+    },
+    // ... more fields
+  ],
+};
+```
+
+```html
+<lib-configurable-form
+  [jsonConfig]="jsonConfig"
+  [baseApiUrl]="'https://api.example.com'"
+  (formSubmit)="onSubmit($event)"
+>
+</lib-configurable-form>
+```
+
+## Mobile Responsive Grid Classes
+
+The component uses a Bootstrap-like grid system:
+
+- `col-1` to `col-12` - Mobile columns (full width by default)
+- `col-md-1` to `col-md-12` - Desktop columns (min-width: 769px)
+- Example: `class: "col-6 col-md-4"` → Half width on mobile, 1/3 on desktop
+
+## Validation Features
+
+- **Required fields**: Visual indicators with red asterisk
+- **Real-time validation**: Validates on blur and form submission
+- **Error messages**: Displays validation errors below fields
+- **Scroll to error**: Automatically scrolls to first invalid field on submit
+- **Composite validation**: Special validators for min-max and percentage totals
+- **File size validation**: Enforces 5MB limit per file
+
+## Best Practices
+
+1. **Use JSON Config for API-driven forms**: When form structure comes from backend
+2. **Use FormConfig for static forms**: When form structure is known at compile time
+3. **Set baseApiUrl**: Provide base URL for cleaner API endpoint configuration
+4. **Use grid classes**: Always specify responsive grid classes for proper layout
+5. **Provide help text**: Add contextual help for complex fields
+6. **Validate composite fields**: Use built-in validators for min-max and percentages
+7. **Handle file uploads**: Process uploaded files in the submit handler
+8. **Pre-fill data**: Use the `data` input to pre-populate forms for editing
+
+## Accessibility
+
+- Semantic HTML structure
+- Proper label associations
+- ARIA attributes for validation states
+- Keyboard navigation support
+- Focus management for error states
+- Screen reader friendly error messages
+
+
+## Playground Example (With Translation Keys and labelsObject)
+
+You can use the following configuration in the UI Playground to test the component with translation keys:
+
+```json
+{
+  "config": {
+    "sections": [
+      {
+        "sectionTitle": "UI_PLAYGROUND.CONFIG_FORM.DONOR.SECTION.INFO",
+        "fields": [
+          {
+            "name": "donorLegalName",
+            "label": "UI_PLAYGROUND.CONFIG_FORM.DONOR.LEGAL_NAME.LABEL",
+            "type": "text",
+            "placeholder": "UI_PLAYGROUND.CONFIG_FORM.DONOR.LEGAL_NAME.PH",
+            "required": true,
+            "class": "col-12"
+          },
+          {
+            "name": "donorType",
+            "label": "UI_PLAYGROUND.CONFIG_FORM.DONOR.TYPE.LABEL",
+            "type": "dropdown",
+            "placeholder": "UI_PLAYGROUND.COMMON.SELECT",
+            "required": true,
+            "options": [
+              {
+                "label": "UI_PLAYGROUND.OPTION.INDIVIDUAL",
+                "value": "individual"
+              },
+              {
+                "label": "UI_PLAYGROUND.OPTION.CORPORATE",
+                "value": "corporate"
+              }
+            ],
+            "class": "col-12"
+          }
+        ]
+      }
+    ]
+  },
+  "labels": {
+    "repeaterItemDefaultLabel": "Item",
+    "addMoreDefaultLabel": "Add More",
+    "selectDefaultPlaceholder": "Select",
+    "errorMinValue": "Min value cannot be greater than Max value.",
+    "errorPercentageTotal": "Total percentage must be 100%.",
+    "uploadDragDropText": "Click to upload File",
+    "uploadHint": "PDF, DOCX, JPG, PNG (Max 5MB)",
+    "charactersLabel": "Characters",
+    "removeFileAriaLabel": "Remove file",
+    "errorFileLimitExceeded": "File {0} exceeds 5MB limit",
+    "errorMaxItemsAllowed": "Maximum {0} items allowed",
+    "closeSnackBar": "Close",
+    "labelsObject": {
+        "UI_PLAYGROUND.CONFIG_FORM.DONOR.SECTION.INFO": "Donor Information",
+        "UI_PLAYGROUND.CONFIG_FORM.DONOR.LEGAL_NAME.LABEL": "Legal Name (Same as PAN)",
+        "UI_PLAYGROUND.CONFIG_FORM.DONOR.LEGAL_NAME.PH": "Enter legal name",
+        "UI_PLAYGROUND.CONFIG_FORM.DONOR.TYPE.LABEL": "Donor Type",
+        "UI_PLAYGROUND.COMMON.SELECT": "Select an option",
+        "UI_PLAYGROUND.OPTION.INDIVIDUAL": "Individual",
+        "UI_PLAYGROUND.OPTION.CORPORATE": "Corporate"
+    }
+  }
+}
+```