platformcommons-web-lib 1.0.0

package/src/lib/modules/smart-form/components/form-field/form-field.component.ts

@@ -0,0 +1,2232 @@
+import { Component, Input, OnInit, OnDestroy, AfterViewInit, ViewChild, ElementRef, HostListener } from '@angular/core';
+import { HttpClient, HttpHeaders, HttpParams } from '@angular/common/http';
+import {
+  FormArray,
+  FormBuilder,
+  FormControl,
+  FormGroup,
+  ValidatorFn,
+  Validators
+} from '@angular/forms';
+import { SectionConfig, FieldConfig, FormLabels, UploadedFile, MediaItem, LocationItem, LocationFieldValue, AttachmentConfig, LibraryUploadConfig, AutocompleteConfig, AutocompleteDisplayField } from '../../models/form-schema.model';
+import { SmartFormController } from '../../services/smart-form-controller.service';
+import { ExpressionService } from '../../services/expression.service';
+import { ValidationUtils } from '../../utils/validation.utils';
+import { StringUtils } from '../../../../utils/string.utils';
+import { Subject, combineLatest, forkJoin, BehaviorSubject, merge } from 'rxjs';
+import { takeUntil, debounceTime, distinctUntilChanged } from 'rxjs/operators';
+import { ConfirmationModalConfig } from '../../../confirmation-modal/confirmation-modal.models';
+
+@Component({
+  selector: 'lib-form-field',
+  templateUrl: './form-field.component.html',
+  styleUrls: ['./form-field.component.scss'],
+  standalone: false
+})
+export class FormFieldComponent implements OnInit, OnDestroy {
+  @Input() config!: FieldConfig;
+  @Input() controller!: SmartFormController;
+  /**
+   * The FormGroup that THIS field's control should be registered in.
+   * For repeater instances this is the instance's own isolated FormGroup.
+   * For flat (non-repeater) fields this is the root formGroup.
+   */
+  @Input() formGroup!: FormGroup;
+
+  /**
+   * Set to TRUE when this field is part of a repeatable group (config.sectionConfig.allowMulti = true).
+   * When true, the field does NOT sync with the global controller to prevent data collision
+   * between different instances of the same repeater row.
+   */
+  @Input() allowMulti: boolean = false;
+
+  value: any;
+  isVisible: boolean = true;
+  showPassword: boolean = false;  // password show/hide toggle
+  dynamicMinDate: string | null = null;
+  dynamicMinTime: string | null = null;
+
+  /**
+   * Effective minimum date for the datepicker.
+   * Priority: dynamic (sibling field) → explicit minDate → today (when allowPast is false).
+   * When allowPast is not false, past dates stay allowed unless an explicit min is set.
+   */
+  get effectiveMinDate(): string | null {
+    const explicitMin = this.dynamicMinDate || this.config.dateConfig?.minDate || null;
+    if (explicitMin) return explicitMin;
+    if (this.config.dateConfig?.allowPast === false) {
+      const now = new Date();
+      const pad = (n: number) => String(n).padStart(2, '0');
+      return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+    }
+    return null;
+  }
+
+  /**
+   * Effective minimum time for the time input.
+   * Priority: dynamic (sibling field) → explicit minTime.
+   * Mirrors {@link effectiveMinDate} for TIME fields.
+   */
+  get effectiveMinTime(): string | null {
+    return this.dynamicMinTime || this.config.timeConfig?.minTime || null;
+  }
+
+  /** Effective maximum time for the time input (explicit maxTime only). */
+  get effectiveMaxTime(): string | null {
+    return this.config.timeConfig?.maxTime || null;
+  }
+
+  // ── MULTIPLE dropdown state ───────────────────────────────────────────────
+  isMultiDropdownOpen: boolean = false;
+  isDragOver: boolean = false;    // file upload drag-over state
+  fileUploadError: string = '';   // per-field file validation error
+  multiSaveError: string = '';    // error for multisave validation
+  private destroy$ = new Subject<void>();
+
+  // ── MEDIA_UPLOAD support ────────────────────────────────────────────────
+  @ViewChild('mediaDeviceInput') mediaDeviceInput!: ElementRef<HTMLInputElement>;
+  /** Host div for the library picker — always in DOM, moved to body to escape parent transforms */
+  @ViewChild('libraryModal') libraryModalRef!: ElementRef<HTMLDivElement>;
+  showMediaMenu: boolean = false;          // hover/click dropdown menu
+  showYoutubeInput: boolean = false;       // inline YouTube URL input panel
+  youtubeUrlInput: string = '';            // model for the YT URL field
+  youtubeUrlError: string = '';            // validation message for YT url
+  mediaCarouselIndex: number = 0;         // active slide index for carousel
+  showLibraryModal: boolean = false;       // library picker modal
+  libraryImages: any[] = [];              // raw list fetched from library API
+  librarySelectedIds: Set<any> = new Set(); // selected library items
+  libraryLoading: boolean = false;
+  libraryError: string = '';
+  mediaUploadError: string = '';           // transient error message for max limits
+
+  // ── LOCATION field support ────────────────────────────────────────────────
+  /** Active tab: any string, e.g. 'VENUE', 'ONLINE', 'TBA'. Defaults to 'VENUE'. */
+  locationActiveTab: string = 'VENUE';
+  /** Current text in the venue search box */
+  locationSearchText: string = '';
+  /** Google Places autocomplete suggestions */
+  locationSuggestions: any[] = [];
+  /** Show the suggestions dropdown */
+  locationShowSuggestions: boolean = false;
+  /** Cached Google AutocompleteService instance */
+  private _googleAcService: any = null;
+  /** Whether Google Maps is loaded */
+  locationMapLoaded: boolean = false;
+  /** Map instance */
+  private _googleMap: any = null;
+  /** Map markers */
+  private _mapMarkers: any[] = [];
+
+  // ── AUTOCOMPLETE support ────────────────────────────────────────────────
+  /** FormControl used ONLY for the autocomplete text-input display value */
+  autocompleteInputCtrl = new FormControl('');
+  /** Filtered option list shown in the mat-autocomplete panel */
+  filteredOptions: { label: string; code: any }[] = [];
+  /**
+   * Component-local option list for DROPDOWN/RADIO/CHECKBOX/CHIP fields.
+   * Using a local copy prevents shared-config mutation when the same field config
+   * object is reused across multiple allowMulti repeater instances.
+   */
+  localOptionList: any[] = [];
+  /** Cache of the latest dependency parameters for server-side autocomplete filtering */
+  private _latestDependencyValues: { [key: string]: any } = {};
+
+  // ── GROUP / allowMulti support ──────────────────────────────────────────
+
+  /** For GROUP fields with allowMulti = true */
+  groupFormArray!: FormArray;
+
+  /** For GROUP fields with allowMulti = false — single nested FormGroup */
+  groupFormGroup!: FormGroup;
+
+  /**
+   * Tracked list of repeater instances.
+   * Using a separate array (not FormArray.controls) + trackBy(id) ensures
+   * Angular creates FRESH child components for every new row, preventing
+   * cached values from bleeding into new instances.
+   *
+   * Enhanced with isEditing and isSaved flags for the 'multiSave' card UI.
+   * Each instance gets its own rowController so cascading dropdowns work
+   * independently within each repeater row.
+   */
+  instanceList: { id: number; fg: FormGroup; initialValue?: any; isEditing?: boolean; isSaved?: boolean; isExpanded?: boolean; rowController: SmartFormController }[] = [];
+  private _nextInstanceId = 0;
+
+  /** Tracks open accordion panels for standard (non-multiSave) GROUP repeaters. */
+  expandedGroupInstances = new Set<number>();
+
+  /**
+   * Key used to register the GROUP control on the parent formGroup.
+   * Priority: sectionConfig.name > field.name > camelCase(label) > '__group__'
+   */
+  get groupKey(): string {
+    return (
+      this.config.sectionConfig?.name ||
+      this.config.name ||
+      StringUtils.toCamelCase(this.config.sectionConfig?.label) ||
+      '__group__'
+    );
+  }
+
+
+  constructor(
+    private fb: FormBuilder,
+    private expressionService: ExpressionService,
+    private http: HttpClient
+  ) { }
+
+  ngOnInit(): void {
+    if (this.isGroup) {
+      this.initGroupField();
+      return;
+    }
+
+    // Seed localOptionList from any static options already in the config
+    // (e.g. optionList defined directly in the JSON like Yes/No dropdowns).
+    // Dynamic options loaded via API will replace this array via loadDropdownOptions.
+    this.localOptionList = [...(this.config.optionConfig?.optionList || [])];
+
+    this.registerControl();
+    this.setupVisibility();
+    this.setupMinDateField();
+    this.setupMinTimeField();
+    this.setupGeneratedField();
+    this.setupFormulaValidation(); // Generic formula-based validation
+    this.setupDependencies();
+    this.setupMatchValidation();  // cross-field match (e.g. confirmPassword)
+
+    if (!this.config.optionConfig?.dependencies) {
+      this.loadDropdownOptions();
+    }
+
+    if (this.isAutocomplete) {
+      this.initAutocomplete();
+    }
+
+    if (this.isLocation) {
+      this.initLocationField();
+    }
+  }
+
+  // ── GROUP initialisation ──────────────────────────────────────────────────
+  get addMultiLabel(): string {
+    const rawLabel = this.config.sectionConfig?.multiSaveConfig?.addLabel;
+    if (rawLabel) {
+      return this.controller.labels?.[rawLabel] || rawLabel;
+    }
+    const sectionLabel = this.config.sectionConfig?.label;
+    const translatedSectionLabel = sectionLabel ? (this.controller.labels?.[sectionLabel] || sectionLabel) : '';
+    return '+ Add a ' + translatedSectionLabel;
+  }
+
+  /** Getter for Select placeholder label */
+  get selectPlaceholderLabel(): string {
+    return this.controller.labels?.['SELECT_PLACEHOLDER'] || 'Select';
+  }
+
+  /** Getter for No options available label */
+  get noOptionsAvailableLabel(): string {
+    return this.controller.labels?.['NO_OPTIONS_AVAILABLE'] || 'No options available';
+  }
+
+  /** Getter for expand less icon name */
+  get expandLessLabel(): string {
+    return this.controller.labels?.['EXPAND_LESS'] || 'expand_less';
+  }
+
+  /** Getter for expand more icon name */
+  get expandMoreLabel(): string {
+    return this.controller.labels?.['EXPAND_MORE'] || 'expand_more';
+  }
+
+  private initGroupField(): void {
+    if (this.config.sectionConfig?.allowMulti) {
+      this.groupFormArray = this.fb.array([]);
+      this.formGroup.addControl(this.groupKey, this.groupFormArray);
+
+      const initialData = this.controller.getFieldValue(this.groupKey);
+      if (Array.isArray(initialData) && initialData.length > 0) {
+        initialData.forEach((item: any) => {
+          this.addGroupInstance(item);
+        });
+      } else {
+        // We always start with at least one instance.
+        // If multi-save is active, it starts in editing mode and is NOT
+        // added to the main form value until the user actually saves it.
+        this.addGroupInstance();
+      }
+    } else {
+      this.groupFormGroup = this.fb.group({});
+      this.formGroup.addControl(this.groupKey, this.groupFormGroup);
+    }
+  }
+
+  /**
+   * Sets up cross-field validation based on the `onValidate` formula.
+   * Watches all variables mentioned in the formula and updates the field's
+   * validity whenever any of them change.
+   */
+  private setupFormulaValidation(): void {
+    if (!this.config.onValidate) return;
+
+    const expression = this.config.onValidate;
+    const variables = this.expressionService.extractVariables(expression);
+
+    // Subscribe to all fields mentioned in the formula
+    const observables = variables.map(v => this.controller.getFieldObservable(v));
+
+    combineLatest(observables).pipe(takeUntil(this.destroy$)).subscribe(() => {
+      const context = this.controller.getAllData();
+      const isValid = this.expressionService.evaluateCondition(expression, context);
+
+      const control = this.formGroup.get(this.config.name!);
+      if (control) {
+        if (!isValid) {
+          control.setErrors({ ...control.errors, formulaError: true });
+        } else {
+          // Clear only the formulaError
+          if (control.hasError('formulaError')) {
+            const errors = { ...control.errors };
+            delete errors['formulaError'];
+            control.setErrors(Object.keys(errors).length ? errors : null);
+          }
+        }
+      }
+    });
+  }
+
+  addGroupInstance(initialData?: any): void {
+    const fg = this.fb.group({});
+    const isMultiSave = !!this.config.sectionConfig?.multiSaveConfig?.active;
+
+    // If initialData exists, treat the instance as already submitted/saved to form
+    const isEditing = initialData ? false : isMultiSave;
+    const isSaved = initialData ? true : !isMultiSave;
+
+    // Per-row controller: inherits token/labels from global but has isolated field state.
+    // This allows cascading dropdowns (dependencies) to work within each repeater row
+    // without cross-row data collisions.
+    const rowController = new SmartFormController();
+    rowController.token = this.controller.token;
+    rowController.tokenHeader = this.controller.tokenHeader;
+    rowController.labels = this.controller.labels;
+    rowController.actionLabels = this.controller.actionLabels;
+
+    // Pre-populate row controller so child fields initialize with the correct values
+    if (initialData) {
+      Object.entries(initialData).forEach(([key, value]) => {
+        rowController.updateField(key, value as any);
+      });
+    }
+
+    const instance = {
+      id: this._nextInstanceId++,
+      fg,
+      isEditing,
+      isSaved,
+      isExpanded: false,
+      initialValue: initialData ? { ...initialData } : undefined,
+      rowController
+    };
+
+    if (isSaved) {
+      this.groupFormArray.push(fg);
+    }
+
+    // Collapse all existing panels; expand only the new one
+    if (!isMultiSave) {
+      this.expandedGroupInstances.clear();
+      this.expandedGroupInstances.add(this.instanceList.length);
+    }
+
+    this.instanceList = [...this.instanceList, instance];
+
+    if (initialData) {
+      setTimeout(() => {
+        // Ensure that controls exist for all keys in initialData so we don't drop fields like ID!
+        Object.keys(initialData).forEach(key => {
+          if (!fg.contains(key)) {
+            fg.addControl(key, new FormControl(initialData[key]));
+          }
+        });
+        fg.patchValue(initialData);
+      });
+    }
+  }
+
+  saveGroupInstance(index: number): void {
+    const instance = this.instanceList[index];
+    const multiCfg = this.config.sectionConfig?.multiSaveConfig;
+
+    if (multiCfg?.active) {
+      // Validate that at least one key field is filled
+      const summaryVal = instance.fg.get(multiCfg.summaryField || '')?.value;
+      const descVal = multiCfg.descriptionField ? instance.fg.get(multiCfg.descriptionField)?.value : null;
+
+      const hasSummary = summaryVal !== null && summaryVal !== undefined && String(summaryVal).trim() !== '';
+      const hasDesc = multiCfg.descriptionField
+        ? (descVal !== null && descVal !== undefined && String(descVal).trim() !== '')
+        : true; // if no desc field defined, we only care about summary or others
+
+      // User rule: If both fields are empty, need to throw error (come from JSON)
+      const bothRequired = !!multiCfg.summaryField && !!multiCfg.descriptionField;
+      if (bothRequired && !hasSummary && !hasDesc) {
+        this.multiSaveError = this.controller.labels['ERR_MSG_EMPTY_MULTI'] || 'Please fill the required fields before saving.';
+        return;
+      }
+
+      this.multiSaveError = '';
+      instance.isSaved = true;
+      instance.isEditing = false;
+      instance.initialValue = { ...instance.fg.value };
+
+      // Push to the parent formArray so its submitted as part of the FormGroup value
+      if (!this.groupFormArray.controls.includes(instance.fg)) {
+        this.groupFormArray.push(instance.fg);
+      }
+    }
+  }
+
+  cancelGroupInstance(index: number): void {
+    const instance = this.instanceList[index];
+    if (!instance.isSaved) {
+      // It was a new, unsaved addition - remove it entirely
+      this.removeGroupInstance(index, true);
+    } else {
+      // Revert to original values
+      if (instance.initialValue) {
+        instance.fg.patchValue(instance.initialValue, { emitEvent: false });
+      }
+      instance.isEditing = false;
+    }
+  }
+
+  editGroupInstance(index: number): void {
+    const instance = this.instanceList[index];
+    instance.isEditing = true;
+    instance.initialValue = { ...instance.fg.value };
+  }
+
+  toggleExpandGroupInstance(index: number): void {
+    const instance = this.instanceList[index];
+    instance.isExpanded = !instance.isExpanded;
+  }
+
+  removeGroupInstance(index: number, force: boolean = false): void {
+    // If not multiSave, we keep the one-row minimum rule.
+    // In multiSave, we can remove it even if it's the last one.
+    const isMultiSave = !!this.config.sectionConfig?.multiSaveConfig?.active;
+
+    if (force || isMultiSave || this.instanceList.length > 1) {
+      const instance = this.instanceList[index];
+      const arrayIndex = this.groupFormArray.controls.indexOf(instance.fg);
+      if (arrayIndex >= 0) {
+        this.groupFormArray.removeAt(arrayIndex);
+      }
+      instance.rowController.destroy();
+      this.instanceList = this.instanceList.filter((_, i) => i !== index);
+
+      // Rebuild accordion expanded set after index shift
+      if (!isMultiSave) {
+        const updated = new Set<number>();
+        this.expandedGroupInstances.forEach(i => {
+          if (i < index) updated.add(i);
+          else if (i > index) updated.add(i - 1);
+        });
+        this.expandedGroupInstances = updated;
+      }
+    }
+  }
+
+  toggleGroupAccordion(index: number): void {
+    if (this.expandedGroupInstances.has(index)) {
+      this.expandedGroupInstances.delete(index);
+    } else {
+      this.expandedGroupInstances.add(index);
+    }
+  }
+
+  isGroupExpanded(index: number): boolean {
+    return this.expandedGroupInstances.has(index);
+  }
+
+  trackByInstanceId(_: number, item: { id: number; fg: FormGroup }): number {
+    return item.id;
+  }
+
+  // ── Leaf control ─────────────────────────────────────────────────────────
+
+  ngAfterViewInit(): void {
+    if (this.libraryModalRef && this.libraryModalRef.nativeElement) {
+      document.body.appendChild(this.libraryModalRef.nativeElement);
+    }
+  }
+
+  // ── Suffix Action Icons ──────────────────────────────────────────────────
+  /** Handles click on a suffix action icon and emits via the controller */
+  onSuffixActionClick(actionId: string): void {
+    if (this.config.name) {
+      this.controller.suffixActionClick$.next({ fieldName: this.config.name, actionId });
+    }
+  }
+
+  ngOnDestroy(): void {
+    // Clean up DOM portal
+    if (this.libraryModalRef && this.libraryModalRef.nativeElement) {
+      if (document.body.contains(this.libraryModalRef.nativeElement)) {
+        document.body.removeChild(this.libraryModalRef.nativeElement);
+      }
+    }
+
+    // Always complete so any subscriptions (e.g. subfields valueChanges) are cleaned up
+    this.destroy$.next();
+    this.destroy$.complete();
+
+    if (this.isGroup) {
+      if (this.config.sectionConfig?.allowMulti) {
+        this.instanceList.forEach(inst => inst.rowController?.destroy());
+      }
+      if (this.formGroup?.contains(this.groupKey)) {
+        this.formGroup.removeControl(this.groupKey);
+      }
+      return;
+    }
+
+    const fieldName = this.config.name;
+    if (fieldName && this.formGroup?.contains(fieldName)) {
+      this.formGroup.removeControl(fieldName);
+    }
+  }
+
+  registerControl(): void {
+    if (!this.config.name || !this.formGroup) return;
+
+    const fieldName = this.config.name;
+    const validators = this.getValidators();
+
+    // When inside a repeater instance, ALWAYS start with defaultValue (never
+    // read from the shared controller — prevents cross-instance value copying).
+    const initialValue = this.allowMulti
+      ? (this.config.defaultValue ?? null)
+      : (this.controller.getFieldValue(fieldName) ?? this.config.defaultValue ?? null);
+
+    let control = this.formGroup.get(fieldName) as FormControl;
+    if (!control) {
+      control = new FormControl(
+        { value: initialValue, disabled: !!this.config.disabled },
+        validators
+      );
+      this.formGroup.addControl(fieldName, control);
+    }
+
+    this.value = control.value;
+
+    if (!this.allowMulti) {
+      // ── Flat field: keep in sync with shared controller ──────────────────
+      control.valueChanges.pipe(takeUntil(this.destroy$)).subscribe(val => {
+        this.value = val;
+        this.controller.updateField(fieldName, val);
+      });
+
+      this.controller.getFieldObservable(fieldName).pipe(takeUntil(this.destroy$)).subscribe(val => {
+        if (val !== control.value) {
+          control.setValue(val, { emitEvent: false });
+          this.value = val;
+        }
+      });
+    } else {
+      // ── Repeater field: local value tracking only ─────────────────────────
+      control.valueChanges.pipe(takeUntil(this.destroy$)).subscribe(val => {
+        this.value = val;
+      });
+    }
+  }
+
+  getValidators(): ValidatorFn[] {
+    const validators: ValidatorFn[] = [];
+    if (this.config.required) validators.push(Validators.required);
+    if (this.config.subType === 'EMAIL') validators.push(Validators.email);
+    if (this.config.subType === 'PASSWORD') {
+      // Minimum 8 chars by default; honour explicit textConfig.length overrides
+      const minLen = this.config.textConfig?.length?.min ?? 8;
+      validators.push(Validators.minLength(minLen));
+    }
+    if (this.config.textConfig?.length) {
+      const { min, max } = this.config.textConfig.length;
+      if (min && this.config.subType !== 'PASSWORD') validators.push(Validators.minLength(min));
+      if (max) validators.push(Validators.maxLength(max));
+    }
+    if (this.config.textConfig?.pattern) validators.push(Validators.pattern(this.config.textConfig.pattern));
+    if (this.config.numberConfig) {
+      const { min, max } = this.config.numberConfig;
+      if (min !== undefined) validators.push(Validators.min(min));
+      if (max !== undefined) validators.push(Validators.max(max));
+    }
+    if (this.config.type === 'RICH_TEXT' && this.config.richTextConfig?.maxLength) {
+      const max = this.config.richTextConfig.maxLength;
+      validators.push((control: import('@angular/forms').AbstractControl) => {
+        if (!control.value) return null;
+        const plainText = String(control.value).replace(/<[^>]*>/g, '');
+        return plainText.length > max
+          ? { 'maxlength': { requiredLength: max, actualLength: plainText.length } }
+          : null;
+      });
+    }
+    return validators;
+  }
+
+  // ── Cross-field match validation (password === confirmPassword) ───────────
+
+  /**
+   * When `textConfig.matchField` is configured, subscribes to value changes on
+   * BOTH this control and the referenced control so the mismatch error updates
+   * instantly whichever field the user edits last.
+   *
+   *  - Values differ  → sets `{ passwordMismatch: true }` on THIS control.
+   *  - Values match   → clears `passwordMismatch` from THIS control.
+   */
+  setupMatchValidation(): void {
+    const matchFieldName = this.config.textConfig?.matchField;
+    if (!matchFieldName || !this.config.name || !this.formGroup) return;
+
+    const thisControl = this.formGroup.get(this.config.name);
+    const otherControl = this.formGroup.get(matchFieldName);
+    if (!thisControl || !otherControl) return;
+
+    const runCheck = () => {
+      const thisVal = thisControl.value;
+      const otherVal = otherControl.value;
+
+      if (thisVal && otherVal && thisVal !== otherVal) {
+        // Both have a value but they differ — flag the mismatch
+        thisControl.setErrors(
+          { ...thisControl.errors, passwordMismatch: true },
+          { emitEvent: false }
+        );
+      } else {
+        // Either one is empty OR they now match — clear the mismatch error
+        if (thisControl.hasError('passwordMismatch')) {
+          const errors = { ...thisControl.errors };
+          delete errors['passwordMismatch'];
+          thisControl.setErrors(
+            Object.keys(errors).length ? errors : null,
+            { emitEvent: false }
+          );
+        }
+      }
+    };
+
+    // Fire when THIS (confirmPassword) field changes
+    thisControl.valueChanges
+      .pipe(takeUntil(this.destroy$))
+      .subscribe(() => runCheck());
+
+    // Also fire when the OTHER (password) field changes so the error clears
+    // as soon as the user corrects the source value
+    otherControl.valueChanges
+      .pipe(takeUntil(this.destroy$))
+      .subscribe(() => runCheck());
+  }
+
+  setupVisibility(): void {
+    if (!this.config.visibilityExpression) return;
+
+    // Prefer formGroup-level lookup: works for both allowMulti rows and non-multi rows
+    // that still have a row-scoped formGroup (e.g. accordion repeater with allowMulti=false).
+    if (this.formGroup) {
+      const variables = this.expressionService.extractVariables(this.config.visibilityExpression);
+      const evaluate = () => {
+        const context = this.formGroup.value;
+        this.isVisible = this.expressionService.evaluateCondition(this.config.visibilityExpression!, context);
+        const control = this.formGroup.get(this.config.name!);
+        if (control) {
+          this.isVisible ? control.enable({ emitEvent: false }) : control.disable({ emitEvent: false });
+        }
+      };
+      evaluate();
+      const varControls = variables
+        .map(v => this.formGroup.get(v))
+        .filter((c): c is FormControl => !!c);
+      const stream$ = varControls.length > 0
+        ? merge(...varControls.map(c => c.valueChanges))
+        : this.formGroup.valueChanges;
+      stream$.pipe(takeUntil(this.destroy$)).subscribe(() => evaluate());
+    } else {
+      const variables = this.expressionService.extractVariables(this.config.visibilityExpression);
+      const observables = variables.map(v => this.controller.getFieldObservable(v));
+      combineLatest(observables).pipe(takeUntil(this.destroy$)).subscribe(() => {
+        const context = this.controller.getAllData();
+        this.isVisible = this.expressionService.evaluateCondition(this.config.visibilityExpression!, context);
+        const control = this.formGroup?.get(this.config.name!);
+        if (control) {
+          this.isVisible ? control.enable({ emitEvent: false }) : control.disable({ emitEvent: false });
+        }
+      });
+    }
+  }
+
+  setupMinDateField(): void {
+    const minDateField = this.config.dateConfig?.minDateField;
+    if (!minDateField || this.config.type !== 'DATE') return;
+
+    // Use local date to avoid UTC-offset day shift (e.g. IST midnight = prev-day UTC)
+    const toIso = (val: any): string | null => {
+      if (!val) return null;
+      const d = val instanceof Date ? val : new Date(val);
+      if (isNaN(d.getTime())) return String(val);
+      const y = d.getFullYear();
+      const mo = String(d.getMonth() + 1).padStart(2, '0');
+      const dy = String(d.getDate()).padStart(2, '0');
+      return `${y}-${mo}-${dy}`;
+    };
+
+    // Prefer formGroup-level lookup: works for both allowMulti rows and non-multi rows
+    // that still have a row-scoped formGroup (e.g. accordion repeater with allowMulti=false).
+    if (this.formGroup) {
+      const sourceCtrl = this.formGroup.get(minDateField);
+      if (sourceCtrl) {
+        this.dynamicMinDate = toIso(sourceCtrl.value);
+        sourceCtrl.valueChanges.pipe(takeUntil(this.destroy$)).subscribe(val => {
+          this.dynamicMinDate = toIso(val);
+          // If end date is now before the new start date, clear it immediately
+          const thisCtrl = this.formGroup?.get(this.config.name!);
+          if (thisCtrl?.value && val) {
+            const endD = thisCtrl.value instanceof Date ? thisCtrl.value : new Date(thisCtrl.value);
+            const minD = val instanceof Date ? val : new Date(val as string);
+            if (!isNaN(endD.getTime()) && !isNaN(minD.getTime()) && endD < minD) {
+              thisCtrl.setValue(null, { emitEvent: true });
+            }
+          }
+        });
+        return;
+      }
+    }
+
+    // Fall back to controller-based lookup (non-repeater flat fields).
+    const updateMin = (context: any) => {
+      this.dynamicMinDate = toIso(context?.[minDateField]);
+    };
+    updateMin(this.controller.getAllData());
+    this.controller.getFieldObservable(minDateField)
+      .pipe(takeUntil(this.destroy$))
+      .subscribe(() => updateMin(this.controller.getAllData()));
+  }
+
+  /**
+   * Wires up a dynamic minimum for a TIME field from a sibling TIME field
+   * (config.timeConfig.minTimeField). When the source changes, this field's
+   * minimum updates and any now-invalid value (earlier than the new minimum)
+   * is cleared. Mirrors {@link setupMinDateField} for TIME fields.
+   */
+  setupMinTimeField(): void {
+    const minTimeField = this.config.timeConfig?.minTimeField;
+    if (!minTimeField || this.config.type !== 'TIME') return;
+
+    // Native <input type="time"> stores an "HH:mm" (or "HH:mm:ss") string,
+    // which compares correctly lexicographically. Normalise anything else to a string.
+    const toTime = (val: any): string | null => {
+      if (val === null || val === undefined || val === '') return null;
+      return String(val);
+    };
+
+    // Prefer formGroup-level lookup so it works for both allowMulti rows and
+    // non-multi rows that still have a row-scoped formGroup (accordion repeaters).
+    if (this.formGroup) {
+      const sourceCtrl = this.formGroup.get(minTimeField);
+      if (sourceCtrl) {
+        this.dynamicMinTime = toTime(sourceCtrl.value);
+        sourceCtrl.valueChanges.pipe(takeUntil(this.destroy$)).subscribe(val => {
+          this.dynamicMinTime = toTime(val);
+          // If this (end) time is now before the new start time, clear it immediately.
+          const thisCtrl = this.formGroup?.get(this.config.name!);
+          const min = this.dynamicMinTime;
+          if (thisCtrl?.value && min && String(thisCtrl.value) < min) {
+            thisCtrl.setValue(null, { emitEvent: true });
+          }
+        });
+        return;
+      }
+    }
+
+    // Fall back to controller-based lookup (non-repeater flat fields).
+    const updateMin = (context: any) => {
+      this.dynamicMinTime = toTime(context?.[minTimeField]);
+    };
+    updateMin(this.controller.getAllData());
+    this.controller.getFieldObservable(minTimeField)
+      .pipe(takeUntil(this.destroy$))
+      .subscribe(() => updateMin(this.controller.getAllData()));
+  }
+
+  setupGeneratedField(): void {
+    if (this.config.type !== 'GENERATED' || !this.config.generatedConfig) return;
+    const variables = this.config.generatedConfig.variables || [];
+    const observables = variables.map(v => this.controller.getFieldObservable(v));
+    combineLatest(observables).pipe(takeUntil(this.destroy$)).subscribe(() => {
+      const context = this.controller.getAllData();
+      const result = this.evaluateFormula(context);
+      if (result !== null && this.config.name) {
+        this.controller.updateField(this.config.name, result);
+      }
+    });
+  }
+
+  evaluateFormula(context: { [key: string]: any }): any {
+    if (!this.config.generatedConfig) return null;
+    const formula = this.config.generatedConfig.formula;
+    const functionName = this.extractFunctionName(formula);
+    if (functionName) {
+      return this.expressionService.evaluateFormula(
+        formula, functionName, context, this.config.generatedConfig.variables
+      );
+    }
+    return null;
+  }
+
+  extractFunctionName(formula: string): string | null {
+    const match = formula.match(/(?:function|fun)\s+(\w+)\s*\(/);
+    return match ? match[1] : null;
+  }
+
+  setupDependencies(): void {
+    if (!this.config.optionConfig?.dependencies) return;
+    const dependencies = this.config.optionConfig.dependencies;
+    const observables = Object.values(dependencies).map(fieldName =>
+      this.controller.getFieldObservable(fieldName)
+    );
+    // Track previous values so we can detect user-driven parent changes vs. initial load.
+    // BehaviorSubjects always emit the current value on subscribe — we must NOT clear the
+    // child's value on that first emission (it would wipe pre-populated edit-mode data).
+    let prevValues: any[] | null = null;
+    combineLatest(observables).pipe(takeUntil(this.destroy$)).subscribe(values => {
+      const dependencyValues: { [key: string]: any } = {};
+      Object.keys(dependencies).forEach((paramKey, index) => {
+        dependencyValues[paramKey] = values[index];
+      });
+      const allPresent = Object.values(dependencyValues).every(
+        v => v !== null && v !== undefined && v !== ''
+      );
+
+      const isFirstEmit = prevValues === null;
+      const parentChanged = !isFirstEmit && values.some((v, i) => v !== prevValues![i]);
+      prevValues = [...values];
+
+      if (allPresent) {
+        if (parentChanged) {
+          // Parent value changed by user interaction — reset child selection so the
+          // previously chosen value (from a different parent) isn't shown as selected
+          // against the newly loaded options.
+          const control = this.formGroup?.get(this.config.name!);
+          if (control && control.value !== null && control.value !== '') {
+            control.setValue(null, { emitEvent: true });
+          }
+        }
+        this._latestDependencyValues = dependencyValues;
+        this.loadDropdownOptions(dependencyValues);
+      } else if (this.config.optionConfig) {
+        this._latestDependencyValues = {};
+        this.localOptionList = [];
+        if (parentChanged) {
+          const control = this.formGroup?.get(this.config.name!);
+          if (control && control.value !== null && control.value !== '') {
+            control.setValue(null, { emitEvent: true });
+          }
+        }
+      }
+    });
+  }
+
+  loadDropdownOptions(dynamicParams: { [key: string]: any } = {}): void {
+    const optionConfig = this.config.optionConfig;
+    const acConfig = this.config.autocompleteConfig;
+
+    const urls = optionConfig?.apiUrls ||
+      (optionConfig?.apiUrl ? [optionConfig.apiUrl] :
+        optionConfig?.optionUrl ? [optionConfig.optionUrl] : []);
+
+    if (!urls || urls.length === 0) return;
+
+    // HTTP method/body/headers: read from autocompleteConfig first, fall back to optionConfig
+    const method = acConfig?.method || 'GET';
+    const staticBody = acConfig?.body ?? null;
+    const staticQueryParams = acConfig?.queryParams || {};
+    const customHeaders = acConfig?.headers;
+
+    const observables = urls.map(url => {
+      let fullUrl = url;
+
+      // Merge static queryParams and dynamicParams
+      const allQueryParams = { ...staticQueryParams, ...dynamicParams };
+
+      // Interpolate path variables (e.g., {program}) from allQueryParams
+      Object.keys(allQueryParams).forEach(key => {
+        const placeholder = `{${key}}`;
+        if (fullUrl.includes(placeholder)) {
+          fullUrl = fullUrl.replace(placeholder, String(allQueryParams[key]));
+          // Remove it so it doesn't get appended as a query param
+          delete allQueryParams[key];
+        }
+      });
+
+      let httpParams = new HttpParams();
+      Object.entries(allQueryParams).forEach(([key, value]) => {
+        if (value !== null && value !== undefined) {
+          httpParams = httpParams.append(key, String(value));
+        }
+      });
+
+      const options: any = {
+        headers: this.getHeaders(customHeaders),
+        params: httpParams
+      };
+
+      switch (method) {
+        case 'POST': return this.http.post<any>(fullUrl, staticBody, options);
+        case 'PUT': return this.http.put<any>(fullUrl, staticBody, options);
+        case 'PATCH': return this.http.patch<any>(fullUrl, staticBody, options);
+        default: return this.http.get<any>(fullUrl, options);
+      }
+    });
+
+    forkJoin(observables).pipe(takeUntil(this.destroy$)).subscribe({
+      next: (responses: any[]) => {
+        let mergedData: any[] = [];
+        responses.forEach((response: any) => {
+          let data = optionConfig?.dataPath
+            ? this.getValueByPath(response, optionConfig.dataPath)
+            : (Array.isArray(response) ? response : response.elements || response.data || response.items || response || []);
+
+          // Handle Dictionary Objects by converting them to Arrays
+          if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+            data = Object.values(data);
+          }
+
+          if (Array.isArray(data)) mergedData = [...mergedData, ...data];
+        });
+
+        if (optionConfig?.sortBy) {
+          const sortKey = optionConfig.sortBy;
+          const direction = optionConfig.sortDirection === 'DESC' ? -1 : 1;
+          mergedData.sort((a, b) => {
+            const valA = this.getValueByPath(a, sortKey);
+            const valB = this.getValueByPath(b, sortKey);
+            if (typeof valA === 'string' && typeof valB === 'string') return direction * valA.localeCompare(valB);
+            if (typeof valA === 'number' && typeof valB === 'number') return direction * (valA - valB);
+            return 0;
+          });
+        }
+
+        // labelTemplate: read from autocompleteConfig first
+        const labelTemplate = acConfig?.labelTemplate;
+
+        this.localOptionList = mergedData.map((item: any) => {
+          // Support labelTemplate: '{firstName} {lastName} ({login})'
+          let label: string;
+          if (labelTemplate) {
+            label = labelTemplate.replace(/\{(\w+)\}/g, (_: string, key: string) => {
+              const val = this.getValueByPath(item, key);
+              return val !== undefined && val !== null ? String(val) : '';
+            });
+          } else if (optionConfig?.labelPath) {
+            label = String(this.getValueByPath(item, optionConfig.labelPath) ?? '');
+          } else {
+            label = item.label || item.displayName || item.name || '';
+          }
+
+          const code = optionConfig?.valuePath
+            ? this.getValueByPath(item, optionConfig.valuePath)
+            : (item.code ?? item.id ?? item.value);
+
+          // Resolve displayFields from autocompleteConfig
+          // Supports string (single path, backward-compat) or AutocompleteDisplayField[]
+          const displayFields = acConfig?.displayFields;
+          let displayMeta: { path: string; type: string; label?: string; value: string }[] | undefined;
+          if (displayFields) {
+            const fields: AutocompleteDisplayField[] = typeof displayFields === 'string'
+              ? [{ path: displayFields, type: 'text' }]
+              : displayFields;
+            displayMeta = fields.map(f => ({
+              path: f.path,
+              type: f.type || 'text',
+              icon: f.icon,
+              className: f.className,
+              label: f.label,
+              value: String(this.getValueByPath(item, f.path) ?? '')
+            })).filter(f => f.value !== '');
+          }
+
+          return { label, code, value: item, displayMeta };
+        });
+
+        // Refresh autocomplete filter list after options arrive from API
+        if (this.isAutocomplete) {
+          this.filteredOptions = [...this.localOptionList];
+          this._syncAutocompleteDisplayValue();
+        }
+      },
+      error: err => console.error('Failed to load dropdown options:', err)
+    });
+  }
+
+  private getValueByPath(obj: any, path: string): any {
+    if (!path || path === '') return obj;
+    return path.split('.').reduce((acc, part) => {
+      const match = part.match(/(\w+)\[(\d+)\]/);
+      if (match) return acc?.[match[1]]?.[parseInt(match[2])];
+      return acc?.[part];
+    }, obj);
+  }
+
+  /**
+   * Replaces `{placeholder}` tokens in a URL with values resolved from the
+   * current form data (supports dot / array-index paths via getValueByPath).
+   * Returns the interpolated URL plus whether EVERY token was resolved.
+   *
+   * Used by the delete flows: when a required id (e.g. `{entityId}`) is missing
+   * — as in CREATE mode before the entity exists — `resolved` is false and the
+   * caller skips the server delete and just removes the item from the form.
+   */
+  private resolveUrlPlaceholders(url: string): { url: string; resolved: boolean } {
+    if (!url || !url.includes('{')) return { url, resolved: true };
+    const data = this.controller.getAllData();
+    let resolved = true;
+    const out = url.replace(/\{([^}]+)\}/g, (_match, path: string) => {
+      const val = this.getValueByPath(data, path.trim());
+      if (val === null || val === undefined || val === '') {
+        resolved = false;
+        return `{${path}}`;
+      }
+      return String(val);
+    });
+    return { url: out, resolved };
+  }
+
+  /** Builds HttpHeaders using the token stored in the SmartFormController (sourced from configJSON)
+   *  merged with any custom headers declared in optionConfig.headers.
+   */
+  private _fileLabel(key: keyof FormLabels, fallback: string, vars: Record<string, string> = {}): string {
+    let tpl = (this.controller.actionLabels?.[key] as string) ?? fallback;
+    Object.entries(vars).forEach(([k, v]) => { tpl = tpl.replace(`{${k}}`, v); });
+    return tpl;
+  }
+
+  private getHeaders(customHeaders?: { [key: string]: string }): HttpHeaders {
+    let headers = new HttpHeaders();
+    if (this.controller.token) {
+      const headerName = this.controller.tokenHeader || 'Authorization';
+      headers = headers.set(headerName, this.controller.token);
+    }
+    // Merge custom headers from optionConfig (allows MFE to pass e.g. X-SESSIONID)
+    if (customHeaders) {
+      Object.entries(customHeaders).forEach(([key, val]) => {
+        headers = headers.set(key, val);
+      });
+    }
+    return headers;
+  }
+
+  updateValue(newValue: any): void {
+    if (!this.config.name) return;
+    const control = this.formGroup.get(this.config.name);
+    if (control) {
+      control.setValue(newValue);
+      control.markAsDirty();
+      control.markAsTouched();
+    }
+  }
+
+  onCheckboxListChange(code: string, checked: boolean): void {
+    if (!this.config.name) return;
+    const currentValue = (this.allowMulti
+      ? (this.formGroup.get(this.config.name)?.value)
+      : this.controller.getFieldValue(this.config.name)) || [];
+    const newValue = checked
+      ? [...currentValue, code]
+      : currentValue.filter((c: string) => c !== code);
+    this.updateValue(newValue);
+  }
+
+  isChecked(code: string): boolean {
+    const value = this.value || [];
+    return Array.isArray(value) && value.includes(code);
+  }
+
+  get errorMessage(): string {
+    if (!this.config.name || !this.formGroup) return '';
+    const control = this.formGroup.get(this.config.name);
+    if (control && control.invalid && (control.touched || control.dirty)) {
+      if (control.hasError('required')) return 'This field is required';
+      if (control.hasError('email')) return 'Invalid email format';
+      if (control.hasError('passwordMismatch')) return 'Passwords do not match';
+      if (control.hasError('formulaError')) return this.config.errorMessage || 'Invalid value';
+      if (control.hasError('minlength')) return `Minimum length is ${control.errors?.['minlength'].requiredLength} characters`;
+      if (control.hasError('maxlength')) return `Maximum length is ${control.errors?.['maxlength'].requiredLength} characters`;
+      if (control.hasError('min')) return `Minimum value is ${control.errors?.['min'].min}`;
+      if (control.hasError('max')) return `Maximum value is ${control.errors?.['max'].max}`;
+      if (control.hasError('pattern')) return this.config.textConfig?.patternMessage || 'Invalid format';
+    }
+    return '';
+  }
+
+  get showCharCount(): boolean {
+    if (this.isTextField && this.config.subType !== 'PHONE') {
+      return !!(this.config.textConfig?.showCharCount && this.config.textConfig?.length?.max);
+    }
+    if (this.isRichText) {
+      return !!(this.config.richTextConfig?.showCharCount && this.config.richTextConfig?.maxLength);
+    }
+    return false;
+  }
+
+  get remainingCharacters(): number | null {
+    if (!this.showCharCount || !this.formGroup || !this.config.name) return null;
+    const currentVal = this.formGroup.get(this.config.name)?.value || '';
+
+    if (this.isTextField && this.config.textConfig?.length?.max) {
+      return Math.max(0, this.config.textConfig.length.max - currentVal.length);
+    }
+    if (this.isRichText && this.config.richTextConfig?.maxLength) {
+      const plainText = String(currentVal).replace(/<[^>]*>/g, '');
+      return Math.max(0, this.config.richTextConfig.maxLength - plainText.length);
+    }
+    return null;
+  }
+
+  // ── MULTIPLE dropdown helpers ─────────────────────────────────────────────
+
+  toggleMultiDropdown(event: MouseEvent): void {
+    event.stopPropagation();
+    this.isMultiDropdownOpen = !this.isMultiDropdownOpen;
+  }
+
+  @HostListener('document:click')
+  onDocumentClick(): void {
+    if (this.isMultiDropdownOpen) {
+      this.isMultiDropdownOpen = false;
+    }
+  }
+
+  @HostListener('document:keydown.escape')
+  onEscapeKey(): void {
+    this.isMultiDropdownOpen = false;
+  }
+
+  get multiSelectedCount(): number {
+    return Array.isArray(this.value) ? this.value.length : 0;
+  }
+
+  // ── Type guards ──────────────────────────────────────────────────────────
+
+  get isTextField(): boolean { return this.config.type === 'TEXT_INPUT'; }
+  get isNumberField(): boolean { return this.config.type === 'NUMBER_INPUT'; }
+  get isDateField(): boolean { return this.config.type === 'DATE'; }
+  get isTimeField(): boolean { return this.config.type === 'TIME'; }
+  get isDropdown(): boolean { return this.config.type === 'DROPDOWN'; }
+  get isAutocomplete(): boolean { return this.config.type === 'AUTOCOMPLETE'; }
+  get isFileUpload(): boolean { return this.config.type === 'FILE_UPLOAD'; }
+  get isMediaUpload(): boolean { return this.config.type === 'MEDIA_UPLOAD'; }
+  get isRadio(): boolean { return this.config.type === 'RADIO'; }
+  get isCheckbox(): boolean { return this.config.type === 'CHECKBOX'; }
+  get isChip(): boolean { return this.config.type === 'CHIP'; }
+  get isSwitch(): boolean { return this.config.type === 'SWITCH'; }
+  get isRating(): boolean { return this.config.type === 'RATING'; }
+  get isRichText(): boolean { return this.config.type === 'RICH_TEXT'; }
+  get isGenerated(): boolean { return this.config.type === 'GENERATED'; }
+  get isRow(): boolean { return this.config.type === 'ROW'; }
+  get isGroup(): boolean { return this.config.type === 'GROUP'; }
+  get isLocation(): boolean { return this.config.type === 'LOCATION'; }
+
+  // ── AUTOCOMPLETE helpers ────────────────────────────────────────────────
+
+  /**
+   * Initialise the separate display-control that drives the mat-autocomplete
+   * text input.  The real form control always stores the *code* value.
+   */
+  private initAutocomplete(): void {
+    // Sync display input whenever the real control value changes externally
+    this._syncAutocompleteDisplayValue();
+
+    // Read search settings from autocompleteConfig (preferred) — no fallback to optionConfig needed
+    const acConfig = this.config.autocompleteConfig;
+    const searchParam = acConfig?.searchParam || acConfig?.searchKey;
+    const minLength = acConfig?.searchMinLength ?? 1;
+    const debounceMs = acConfig?.searchDebounce ?? (searchParam ? 300 : 150);
+
+    // Filter the option list as the user types
+    this.autocompleteInputCtrl.valueChanges
+      .pipe(
+        debounceTime(debounceMs),
+        distinctUntilChanged(),
+        takeUntil(this.destroy$)
+      )
+      .subscribe(search => {
+        const query = typeof search === 'string' ? search : '';
+
+        if (searchParam) {
+          if (query.length >= minLength) {
+            // Trigger server-side search merged with active dependencies
+            const params = { ...this._latestDependencyValues, [searchParam]: query };
+            this.loadDropdownOptions(params);
+          } else {
+            // If query is below min length, revert to existing full list if empty query
+            this.filteredOptions = query.length === 0 ? [...this.localOptionList] : [];
+          }
+        } else {
+          // Local filter
+          this.filteredOptions = this._filterOptions(query);
+        }
+      });
+
+    // Initialise filtered list with all available options
+    this.filteredOptions = [...this.localOptionList];
+  }
+
+  /** Filter options by the user's search text (matches label or code). */
+  private _filterOptions(search: string): { label: string; code: any }[] {
+    const q = search.toLowerCase().trim();
+    if (!q) return [...this.localOptionList];
+    return this.localOptionList.filter(opt =>
+      opt.label?.toLowerCase().includes(q) ||
+      String(opt.code).toLowerCase().includes(q)
+    );
+  }
+
+  /** Put the human-readable label into the display control based on the stored code. */
+  private _syncAutocompleteDisplayValue(): void {
+    if (!this.config.name) return;
+    const code = this.formGroup?.get(this.config.name)?.value;
+    if (code === null || code === undefined || code === '') return;
+    const matched = this.localOptionList.find(o => o.code === code);
+    if (matched) {
+      this.autocompleteInputCtrl.setValue(matched.label, { emitEvent: false });
+    }
+  }
+
+  /** Called when user picks an option from the mat-autocomplete panel. */
+  onAutocompleteSelected(option: { label: string; code: any }): void {
+    this.autocompleteInputCtrl.setValue(option.label, { emitEvent: false });
+    this.updateValue(option.code);
+  }
+
+  /** Called when the input loses focus — clear display & value if text was manually deleted. */
+  onAutocompleteClear(): void {
+    const display = (this.autocompleteInputCtrl.value || '').trim();
+    if (!display) {
+      this.updateValue(null);
+    } else {
+      // Restore label from stored code (prevents partial text staying)
+      this._syncAutocompleteDisplayValue();
+    }
+  }
+
+  /**
+   * Returns the effective grid column span for a child inside a ROW.
+   * If the child declares an explicit colSpan, use it.
+   * Otherwise divide 12 equally among all children (floor, min 1).
+   */
+  getChildColSpan(child: FieldConfig): number {
+    if (child.colSpan) return child.colSpan;
+    const count = this.config.children?.length || 1;
+    return Math.max(1, Math.floor(12 / count));
+  }
+
+  getOptionColSpan(option: any): number {
+    const span = option.colSpan || option.colspan;
+    if (span) return span;
+    const count = this.localOptionList.length || 1;
+    return Math.max(1, Math.floor(12 / count));
+  }
+
+  // ── Rating helpers ───────────────────────────────────────────────────────
+
+  onRatingChange(star: number, event?: MouseEvent): void {
+    if (!this.config.name || this.config.disabled) return;
+    let newValue = star;
+    if (this.config.ratingConfig?.allowHalf && event) {
+      const target = event.target as HTMLElement;
+      const rect = target.getBoundingClientRect();
+      if (event.clientX - rect.left < rect.width / 2) newValue = star - 0.5;
+    }
+    if (this.value === newValue) newValue = 0;
+    this.updateValue(newValue);
+  }
+
+  getStarArray(): number[] {
+    const max = this.config.ratingConfig?.maxRating || 5;
+    return Array.from({ length: max }, (_, i) => i + 1);
+  }
+
+  isStarHalf(star: number): boolean { return (this.value || 0) === star - 0.5; }
+  isStarFilled(star: number): boolean { return (this.value || 0) >= star; }
+
+  // ── File Upload helpers ──────────────────────────────────────────────────
+
+  onDragOver(event: DragEvent): void {
+    event.preventDefault();
+    event.stopPropagation();
+    this.isDragOver = true;
+  }
+
+  onDragLeave(event: DragEvent): void {
+    event.preventDefault();
+    event.stopPropagation();
+    this.isDragOver = false;
+  }
+
+  onFileDrop(event: DragEvent): void {
+    event.preventDefault();
+    event.stopPropagation();
+    this.isDragOver = false;
+    const files = event.dataTransfer?.files;
+    if (files && files.length > 0) {
+      this.processFiles(files);
+    }
+  }
+
+  onFileSelected(event: Event): void {
+    const input = event.target as HTMLInputElement;
+    if (input.files && input.files.length > 0) {
+      this.processFiles(input.files);
+    }
+    // Reset input so the same file can be re-selected if removed
+    input.value = '';
+  }
+
+  private processFiles(files: FileList): void {
+    // ── MEDIA_UPLOAD branch — uses attachmentConfig, stores MediaItem[] ─────
+    if (this.isMediaUpload) {
+      const mediaCfg = this.config.attachmentConfig;
+      if (!mediaCfg) return;
+      const maxItems = mediaCfg.maxFiles ?? 10;
+
+      let errorShown = false;
+
+      Array.from(files).forEach(file => {
+        if (this.mediaItems.length >= maxItems) {
+          if (!errorShown) {
+            this.showMediaError(this.controller.labels['ERR_MEDIA_MAX'] || `Maximum ${maxItems} media items allowed.`);
+            errorShown = true;
+          }
+          return;
+        }
+
+        const placeholder: MediaItem = { mediaType: 'image', url: '', isUploading: true };
+        this._appendMediaItem(placeholder);
+        this.controller.fileAdded$.next(file);
+
+        const formData = new FormData();
+        formData.append('file', file);
+
+        if (!mediaCfg.uploadUrl) return;
+        let finalUrl = mediaCfg.uploadUrl;
+        if (finalUrl.includes('{fileName}')) {
+          finalUrl = finalUrl.replace('{fileName}', encodeURIComponent(file.name));
+        }
+
+        this.http.post<any>(finalUrl, formData, { headers: this.getHeaders() })
+          .pipe(takeUntil(this.destroy$))
+          .subscribe({
+            next: (response: any) => {
+              // API returns { completeURL, id, mimeType, fileName, ... }
+              const resolvedUrl: string = (response?.completeURL ?? response)?.toString().trim();
+              const current: MediaItem[] = [...this.mediaItems];
+              const idx = current.indexOf(placeholder);
+              if (idx !== -1) {
+                current[idx] = {
+                  mediaType: 'image',
+                  url: resolvedUrl,
+                  id: response?.id,
+                  mimeType: response?.mimeType,
+                  fileName: response?.fileName ?? response?.name,
+                  isUploading: false
+                };
+                this.updateValue(current);
+                this.mediaCarouselIndex = current.length - 1;
+                this.controller.fileUploadFinished$.next(file);
+              }
+            },
+            error: () => {
+              const cleaned = this.mediaItems.filter(m => m !== placeholder);
+              this.updateValue(cleaned.length ? cleaned : null);
+              this.controller.fileUploadFinished$.next(file);
+            }
+          });
+      });
+      return;
+    }
+
+    // ── FILE_UPLOAD branch — uses attachmentConfig, stores UploadedFile[] ────
+    this.fileUploadError = '';
+    const cfg = this.config.attachmentConfig;
+    const maxSizeBytes = (cfg?.maxSizeMB ?? 10) * 1024 * 1024;
+    const currentFiles: UploadedFile[] = (this.value as UploadedFile[]) || [];
+    const maxFiles = cfg?.maxFiles ?? (cfg?.multiple ? 10 : 1);
+    const isMultiple = cfg?.multiple ?? false;
+
+    const incoming = Array.from(files);
+
+    for (const file of incoming) {
+      // File type validation
+      if (cfg?.accept) {
+        const accepted = cfg.accept.split(',').map((s: string) => s.trim().toLowerCase());
+        const fileExt = '.' + file.name.toLowerCase().split('.').pop();
+        const fileMime = (file.type || '').toLowerCase();
+        const isAllowed = accepted.some((pattern: string) => {
+          if (pattern.startsWith('.')) return fileExt === pattern;
+          if (pattern.endsWith('/*')) return fileMime.startsWith(pattern.slice(0, -1));
+          return fileMime === pattern;
+        });
+        if (!isAllowed) {
+          this.fileUploadError = this._fileLabel('fileTypeError', '"{fileName}" is not a supported file type.', { fileName: file.name });
+          continue;
+        }
+      }
+      // Size validation
+      if (file.size > maxSizeBytes) {
+        this.fileUploadError = this._fileLabel('fileSizeError', '"{fileName}" exceeds the maximum allowed size of {maxSizeMB} MB.', { fileName: file.name, maxSizeMB: String(cfg?.maxSizeMB ?? 10) });
+        continue;
+      }
+      // Max-files validation
+      if (isMultiple && currentFiles.length >= maxFiles) {
+        this.fileUploadError = this._fileLabel('maxFilesError', 'Maximum {maxFiles} files allowed.', { maxFiles: String(maxFiles) });
+        break;
+      }
+
+      if (cfg?.uploadUrl) {
+        // ── API upload path ───────────────────────────────────────────────
+        const entry: UploadedFile = {
+          name: file.name,
+          size: file.size,
+          type: file.type,
+          file,
+          isUploading: true
+        };
+
+        // Add the placeholder entry immediately so the UI shows the progress row
+        const withPlaceholder = isMultiple
+          ? [...(this.value as UploadedFile[] || []), entry]
+          : [entry];
+        this.updateValue(withPlaceholder);
+        this.controller.fileAdded$.next(file);
+
+        const formData = new FormData();
+        formData.append('file', file);
+
+        let finalUrl = cfg.uploadUrl;
+        if (finalUrl.includes('{fileName}')) {
+          finalUrl = finalUrl.replace('{fileName}', encodeURIComponent(file.name));
+        }
+
+        this.http.post<any>(finalUrl, formData, { headers: this.getHeaders() })
+          .pipe(takeUntil(this.destroy$))
+          .subscribe({
+            next: (response: any) => {
+              // The API returns a JSON object; use completeURL if present,
+              // otherwise fall back to treating the raw response as a URL string.
+              const resolvedUrl: string = (response?.completeURL ?? response)?.toString().trim();
+              const current: UploadedFile[] = (this.value as UploadedFile[]) || [];
+              const idx = current.indexOf(entry);
+              if (idx !== -1) {
+                const updatedEntry: UploadedFile = { ...entry, dataUrl: resolvedUrl, id: response?.id, isUploading: false };
+                const updatedList = [...current];
+                updatedList[idx] = updatedEntry;
+                this.updateValue(updatedList);
+                this.controller.fileUploadFinished$.next(file);
+              }
+            },
+            error: () => {
+              // Remove the failed placeholder from the list
+              const current: UploadedFile[] = (this.value as UploadedFile[]) || [];
+              const cleaned = current.filter(f => f !== entry);
+              this.updateValue(cleaned.length ? cleaned : null);
+              this.fileUploadError = this._fileLabel('fileUploadFailed', 'Failed to upload "{fileName}". Please try again.', { fileName: file.name });
+              this.controller.fileUploadFinished$.next(file);
+            }
+          });
+      } else {
+        // ── FileReader (base64) fallback path ────────────────────────────
+        const reader = new FileReader();
+        reader.onload = (e) => {
+          const entry: UploadedFile = {
+            name: file.name,
+            size: file.size,
+            type: file.type,
+            dataUrl: e.target?.result as string,
+            file
+          };
+          const updated = isMultiple
+            ? [...(this.value as UploadedFile[] || []), entry]
+            : [entry];
+          this.updateValue(updated);
+        };
+        reader.readAsDataURL(file);
+      }
+    }
+  }
+
+  removeUploadedFile(index: number): void {
+    const current: UploadedFile[] = (this.value as UploadedFile[]) || [];
+    const fileToRemove = current[index];
+    if (!fileToRemove) return;
+
+    const removeLocally = () => {
+      const updated = current.filter((_, i) => i !== index);
+      this.updateValue(updated);
+    };
+
+    const deleteUrl = this.config.attachmentConfig?.deleteUrl;
+    const { url: resolvedDeleteUrl, resolved } = deleteUrl
+      ? this.resolveUrlPlaceholders(deleteUrl)
+      : { url: '', resolved: false };
+
+    if (fileToRemove.id && fileToRemove.id !== 0 && deleteUrl && resolved) {
+      fileToRemove.isUploading = true; // Use this flag to disable the remove button
+      this.updateValue([...current]); // trigger UI update
+
+      let params = new HttpParams();
+      if (!resolvedDeleteUrl.includes('attachmentId=')) {
+        params = params.set('attachmentId', fileToRemove.id.toString());
+      }
+      if (!resolvedDeleteUrl.includes('reason=')) {
+        // As requested in the API link, the reason is passed
+        params = params.set('reason', 'DELETED BY CREATOR');
+      }
+
+      this.http.delete<any>(resolvedDeleteUrl, { headers: this.getHeaders(), params })
+        .pipe(takeUntil(this.destroy$))
+        .subscribe({
+          next: () => {
+            removeLocally();
+            this.controller.fileRemoved$.next(fileToRemove);
+          },
+          error: (err) => {
+            console.error('Failed to delete attachment', err);
+            fileToRemove.isUploading = false;
+            this.fileUploadError = this._fileLabel('fileDeleteFailed', 'Failed to delete "{fileName}". Please try again.', { fileName: fileToRemove.name });
+            this.updateValue([...current]);
+          }
+        });
+    } else {
+      // No id, no deleteUrl, or an unresolved URL placeholder (e.g. {entityId}
+      // in CREATE mode): just remove locally, no server delete call.
+      removeLocally();
+      this.controller.fileRemoved$.next(fileToRemove);
+    }
+  }
+
+  getFileIcon(mimeType: string): string {
+    if (!mimeType) return 'attach_file';  // guard: undefined/null from non-FILE_UPLOAD values
+    if (mimeType.includes('pdf')) return 'picture_as_pdf';
+    if (mimeType.includes('image')) return 'image';
+    if (mimeType.includes('word') || mimeType.includes('document')) return 'description';
+    if (mimeType.includes('sheet') || mimeType.includes('excel') || mimeType.includes('csv')) return 'table_chart';
+    if (mimeType.includes('zip') || mimeType.includes('compressed')) return 'folder_zip';
+    return 'attach_file';
+  }
+
+  formatFileSize(bytes: number): string {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  }
+
+  // ── Action Labels ──────────────────────────────────────────────────────────
+
+  get addLabel(): string {
+    const key = this.controller.actionLabels?.addLabel || 'Add';
+    return this.controller.labels[key] || key;
+  }
+
+  get removeLabel(): string {
+    const key = this.controller.actionLabels?.removeLabel || 'Remove';
+    return this.controller.labels[key] || key;
+  }
+
+  // ── MEDIA_UPLOAD helpers ─────────────────────────────────────────────────
+
+  get mediaItems(): MediaItem[] {
+    return (this.value as MediaItem[]) || [];
+  }
+
+  /** Number of active items (used to clamp carousel index) */
+  get mediaCount(): number { return this.mediaItems.length; }
+
+  /** The currently visible carousel item */
+  get activeMediaItem(): MediaItem | null {
+    if (!this.mediaItems.length) return null;
+    return this.mediaItems[Math.min(this.mediaCarouselIndex, this.mediaItems.length - 1)];
+  }
+
+  /** Thumbnail strip items */
+  get mediaThumbnails(): MediaItem[] { return this.mediaItems; }
+
+  mediaCarouselPrev(): void {
+    if (this.mediaCarouselIndex > 0) this.mediaCarouselIndex--;
+  }
+
+  mediaCarouselNext(): void {
+    if (this.mediaCarouselIndex < this.mediaItems.length - 1) this.mediaCarouselIndex++;
+  }
+
+  mediaGoTo(index: number): void {
+    this.mediaCarouselIndex = index;
+  }
+
+  // ── YouTube ──────────────────────────────────────────────────────────────
+
+  onMediaMenuVideo(): void {
+    this.showMediaMenu = false;
+    this.showYoutubeInput = !this.showYoutubeInput;
+    this.youtubeUrlInput = '';
+    this.youtubeUrlError = '';
+  }
+
+  addYoutubeMedia(): void {
+    const cfg = this.config.attachmentConfig;
+    const maxItems = cfg?.maxFiles ?? 10;
+    if (this.mediaItems.length >= maxItems) {
+      this.showMediaError(this.controller.labels['ERR_MEDIA_MAX'] || `Maximum ${maxItems} media items allowed.`);
+      return;
+    }
+
+    const url = this.youtubeUrlInput.trim();
+    const videoId = this._extractYoutubeId(url);
+    if (!videoId) {
+      this.youtubeUrlError = this.controller.labels['ERR_INVALID_YOUTUBE_URL'] || 'Please enter a valid YouTube URL.';
+      return;
+    }
+    const item: MediaItem = {
+      mediaType: 'youtube',
+      url: `https://www.youtube.com/embed/${videoId}`,
+      thumbnailUrl: `https://img.youtube.com/vi/${videoId}/mqdefault.jpg`
+    };
+    this._appendMediaItem(item);
+    this.showYoutubeInput = false;
+    this.youtubeUrlInput = '';
+    this.youtubeUrlError = '';
+  }
+
+  private _extractYoutubeId(url: string): string | null {
+    const patterns = [
+      /(?:youtube\.com\/watch\?v=|youtu\.be\/|youtube\.com\/embed\/)([\w-]{11})/,
+      /youtube\.com\/shorts\/([\w-]{11})/
+    ];
+    for (const p of patterns) {
+      const m = url.match(p);
+      if (m) return m[1];
+    }
+    return null;
+  }
+
+  // ── Device upload ────────────────────────────────────────────────────────
+
+  onMediaMenuDevice(): void {
+    this.showMediaMenu = false;
+    this.showYoutubeInput = false;
+    // Use setTimeout so Angular finishes closing the dropdown before the
+    // browser opens the native file picker (the input lives outside *ngIf).
+    setTimeout(() => this.mediaDeviceInput?.nativeElement?.click());
+  }
+
+  onMediaFileSelected(event: Event): void {
+    const input = event.target as HTMLInputElement;
+    if (input.files && input.files.length > 0) {
+      this.processFiles(input.files);
+    }
+    input.value = '';
+  }
+
+  // ── Library helpers ──────────────────────────────────────────────────────
+
+  /**
+   * Resolves the library-image sync POST endpoint from `attachmentConfig.libraryConfig.uploadConfig`.
+   * Returns `null` when not configured; the caller skips the API call.
+   */
+  private buildLibraryUploadRequest(
+    cfg: AttachmentConfig | undefined,
+    runtimeContext: Record<string, any>
+  ): { baseUrl: string; params: HttpParams } | null {
+    const uploadConfig = cfg?.libraryConfig?.uploadConfig;
+    if (!uploadConfig) return null;
+
+    const { baseUrl, params: paramDefs = [] } = uploadConfig;
+    let params = new HttpParams();
+
+    for (const def of paramDefs) {
+      let value: string | undefined;
+
+      // sourcePath takes precedence over staticValue
+      if (def.sourcePath) {
+        const resolved = def.sourcePath
+          .split('.')
+          .reduce((obj: Record<string, any>, k: string) => obj?.[k], runtimeContext);
+        if (resolved !== null && resolved !== undefined) {
+          value = String(resolved);
+        }
+      }
+
+      if (!value && def.staticValue) {
+        value = def.staticValue;
+      }
+
+      if (def.required && !value) {
+        console.warn(`[SmartForm] libraryConfig.uploadConfig: required param "${def.key}" could not be resolved.`);
+        return null;
+      }
+
+      if (value) {
+        params = params.set(def.key, value);
+      }
+    }
+
+    return { baseUrl, params };
+  }
+
+  // ── Library picker ───────────────────────────────────────────────────────
+
+  /** Config object for the cc-confirmation-modal used as the library picker. */
+  get libraryModalConfig(): ConfirmationModalConfig {
+    const labels = this.controller.labels;
+    return {
+      title: labels['LBL_ADD_IMAGES'] || 'Add Images',
+      headerTheme: 'dark' as const,
+      size: 'lg',
+      closeOnBackdrop: true,
+      closeOnEsc: true,
+      showCloseButton: true,
+      cancelButton: {
+        show: true,
+        label: labels['LBL_CANCEL'] || 'Cancel'
+      },
+      confirmButton: {
+        label: labels['LBL_CONTINUE'] || 'Continue',
+        type: 'primary' as const
+      }
+    };
+  }
+
+  onMediaMenuLibrary(): void {
+    this.showMediaMenu = false;
+    this.showYoutubeInput = false;
+    this.libraryImages = [];
+    this.librarySelectedIds = new Set();
+    this.libraryError = '';
+    this.showLibraryModal = true;
+    this._loadLibraryImages();
+  }
+
+  private _loadLibraryImages(): void {
+    const cfg = this.config.attachmentConfig;
+    const libCfg = cfg?.libraryConfig;
+    if (!libCfg?.apiUrl) { this.libraryError = 'Library not configured.'; return; }
+    this.libraryLoading = true;
+    this.http.get<any>(libCfg.apiUrl, { headers: this.getHeaders() })
+      .pipe(takeUntil(this.destroy$))
+      .subscribe({
+        next: (res: any) => {
+          let data: any;
+
+          if (libCfg.dataPath) {
+            // Try explicit dot-notation path configured by the dev (e.g. 'data.items')
+            data = this.getValueByPath(res, libCfg.dataPath);
+          }
+
+          // If no array was found at the configured path, try auto-detecting
+          // the array from common structures
+          if (!Array.isArray(data)) {
+            if (Array.isArray(res)) {
+              // API returned a plain array
+              data = res;
+            } else if (res && typeof res === 'object') {
+              // API returned an object keyed by entity-id e.g. { "1": [...], "2": [...] }
+              // Flatten all value-arrays into one list
+              data = (Object.values(res) as any[][])
+                .filter(v => Array.isArray(v))
+                .reduce((acc, arr) => acc.concat(arr), []);
+            }
+          }
+
+          this.libraryImages = Array.isArray(data) ? data : [];
+          this.libraryLoading = false;
+        },
+        error: () => {
+          this.libraryError = this.controller.labels['ERR_LIBRARY_LOAD_FAILED'] || 'Failed to load library images.';
+          this.libraryLoading = false;
+        }
+      });
+  }
+
+  getLibraryItemUrl(item: any): string {
+    const libCfg = this.config.attachmentConfig?.libraryConfig;
+    return libCfg?.urlPath ? this.getValueByPath(item, libCfg.urlPath) : (item?.url || item?.completeURL || '');
+  }
+
+  getLibraryItemId(item: any): any {
+    const libCfg = this.config.attachmentConfig?.libraryConfig;
+    return libCfg?.idPath ? this.getValueByPath(item, libCfg.idPath) : (item?.id ?? item);
+  }
+
+  isLibraryItemSelected(item: any): boolean {
+    return this.librarySelectedIds.has(this.getLibraryItemId(item));
+  }
+
+  toggleLibraryItem(item: any): void {
+    const id = this.getLibraryItemId(item);
+    if (this.librarySelectedIds.has(id)) {
+      this.librarySelectedIds.delete(id);
+    } else {
+      this.librarySelectedIds.add(id);
+    }
+  }
+
+  closeLibraryModal(): void {
+    this.showLibraryModal = false;
+  }
+
+  confirmLibrarySelection(): void {
+    const selectedItems = this.libraryImages.filter(item => this.isLibraryItemSelected(item));
+
+    if (!selectedItems.length) {
+      this.showLibraryModal = false;
+      return;
+    }
+
+    const cfg = this.config.attachmentConfig;
+    const maxItems = cfg?.maxFiles ?? 10;
+    // NOTE: track added count live — do NOT snapshot currentItems here
+    let errorShown = false;
+
+    // Close modal immediately so UI feels responsive
+    this.showLibraryModal = false;
+
+    selectedItems.forEach(item => {
+      // Use live count — this.mediaItems grows as _appendMediaItem is called
+      if (this.mediaItems.length >= maxItems) {
+        if (!errorShown) {
+          this.showMediaError(this.controller.labels['ERR_MEDIA_MAX'] || `Maximum ${maxItems} media items allowed.`);
+          errorShown = true;
+        }
+        return;
+      }
+      const libraryUrl = this.getLibraryItemUrl(item);
+
+      if (!libraryUrl) return;
+
+      const placeholder: MediaItem = {
+        mediaType: 'image',
+        url: libraryUrl,
+        mimeType: item.mimeType,
+        fileName: item.fileName ?? item.name,
+        isUploading: true
+      };
+
+      this._appendMediaItem(placeholder);
+
+      // Build the POST request using the structured config or legacy URL fallback.
+      // The runtime context provides dynamic param values (e.g. the selected image URL).
+      const request = this.buildLibraryUploadRequest(cfg, { libraryItem: { url: libraryUrl } });
+
+      if (request) {
+        // For legacy fallback the completeUrl param is not yet on params — add it now.
+        // For the structured config it is declared via sourcePath='libraryItem.url' so
+        // it gets resolved inside buildLibraryUploadRequest and is already on params.
+        let { baseUrl, params } = request;
+        if (!params.has('completeUrl')) {
+          params = params.set('completeUrl', libraryUrl);
+        }
+
+        // POST with null body — all data travels as query params
+        this.http.post<any>(baseUrl, null, { headers: this.getHeaders(), params })
+          .pipe(takeUntil(this.destroy$))
+          .subscribe({
+            next: (response: any) => {
+              const current: MediaItem[] = [...this.mediaItems];
+              const idx = current.indexOf(placeholder);
+              if (idx !== -1) {
+                const resolvedUrl: string = (response?.completeURL ?? response)?.toString().trim();
+                current[idx] = {
+                  mediaType: 'image',
+                  url: resolvedUrl,
+                  id: response?.id,
+                  mimeType: response?.mimeType ?? placeholder.mimeType,
+                  fileName: response?.fileName ?? response?.name ?? placeholder.fileName,
+                  isUploading: false
+                };
+                this.updateValue(current);
+              }
+            },
+            error: (err) => {
+              console.error('Failed to sync library image to attachments:', err);
+              const current: MediaItem[] = [...this.mediaItems];
+              const cleaned = current.filter(m => m !== placeholder);
+              this.updateValue(cleaned.length ? cleaned : null);
+            }
+          });
+      } else {
+        // No sync URL configured — use the library URL directly (local-only fallback)
+        const current: MediaItem[] = [...this.mediaItems];
+        const idx = current.indexOf(placeholder);
+        if (idx !== -1) {
+          current[idx] = { ...placeholder, isUploading: false };
+          this.updateValue(current);
+        }
+      }
+    });
+
+    this.mediaCarouselIndex = this.mediaItems.length - 1;
+  }
+
+  // ── Remove item ──────────────────────────────────────────────────────────
+
+  removeMediaItem(index: number): void {
+    const items: MediaItem[] = [...this.mediaItems];
+    const item = items[index];
+    if (!item) return;
+
+    const removeLocally = () => {
+      const updated = items.filter((_, i) => i !== index);
+      this.updateValue(updated.length ? updated : null);
+      // Clamp carousel index so it never points past the end
+      this.mediaCarouselIndex = Math.max(0, this.mediaCarouselIndex - (index <= this.mediaCarouselIndex ? 1 : 0));
+    };
+
+    const deleteUrl = this.config.attachmentConfig?.deleteUrl;
+    const { url: resolvedDeleteUrl, resolved } = deleteUrl
+      ? this.resolveUrlPlaceholders(deleteUrl)
+      : { url: '', resolved: false };
+
+    if (item.id && item.id !== 0 && deleteUrl && resolved) {
+      // ── API delete path (same logic as removeUploadedFile) ───────────────
+      item.isUploading = true;       // disable the remove button while in-flight
+      this.updateValue([...items]);  // trigger change detection
+
+      let params = new HttpParams();
+      if (!resolvedDeleteUrl.includes('attachmentId=')) {
+        params = params.set('attachmentId', item.id.toString());
+      }
+      if (!resolvedDeleteUrl.includes('reason=')) {
+        params = params.set('reason', 'DELETED BY CREATOR');
+      }
+
+      this.http.delete<any>(resolvedDeleteUrl, { headers: this.getHeaders(), params })
+        .pipe(takeUntil(this.destroy$))
+        .subscribe({
+          next: () => {
+            removeLocally();
+            this.controller.fileRemoved$.next(item);
+          },
+          error: (err) => {
+            console.error('Failed to delete media attachment', err);
+            item.isUploading = false;
+            this.updateValue([...items]);  // restore UI state
+          }
+        });
+    } else {
+      // ── No id, no deleteUrl, or an unresolved URL placeholder (e.g.
+      //    {entityId} in CREATE mode before the entity exists): just remove
+      //    the item from the form — no server delete call. ─────────────────
+      removeLocally();
+      this.controller.fileRemoved$.next(item);
+    }
+  }
+
+
+  private _appendMediaItem(item: MediaItem): void {
+    const current: MediaItem[] = [...this.mediaItems];
+    current.push(item);
+    this.updateValue(current);
+    this.mediaCarouselIndex = current.length - 1;
+  }
+
+  private showMediaError(msg: string): void {
+    this.mediaUploadError = msg;
+    setTimeout(() => {
+      if (this.mediaUploadError === msg) this.mediaUploadError = '';
+    }, 4000);
+  }
+
+  // ── LOCATION field methods ─────────────────────────────────────────────────
+
+  private initLocationField(): void {
+    const cfg = this.config.locationConfig;
+    this.locationActiveTab = cfg?.defaultTab ?? 'VENUE';
+
+    // Restore from existing form value using the robust getter
+    if (this.locationValue.tab) {
+      this.locationActiveTab = this.locationValue.tab;
+    }
+
+    // Subscribe to external patchValue events (prefills)
+    this.formGroup.get(this.config.name!)?.valueChanges
+      .pipe(takeUntil(this.destroy$))
+      .subscribe(() => {
+        if (this.locationValue.tab) {
+          this.locationActiveTab = this.locationValue.tab;
+        }
+        setTimeout(() => this._renderMap());
+      });
+
+    // Load Google Maps script if not already loaded
+    this._ensureGoogleMapsScript();
+  }
+
+  private _ensureGoogleMapsScript(): void {
+    const apiKey = this.config.locationConfig?.googleMapsApiKey;
+    if (!apiKey) return;
+
+    if ((window as any).google?.maps?.places) {
+      this._googleAcService = new (window as any).google.maps.places.AutocompleteService();
+      this.locationMapLoaded = true;
+      setTimeout(() => this._renderMap(), 100);
+      return;
+    }
+
+    // Only inject once
+    if (document.querySelector('script[data-sf-gmaps]')) {
+      // Wait for the script to load
+      const wait = () => {
+        if ((window as any).google?.maps?.places) {
+          this._googleAcService = new (window as any).google.maps.places.AutocompleteService();
+          this.locationMapLoaded = true;
+          setTimeout(() => this._renderMap(), 100);
+        } else {
+          setTimeout(wait, 300);
+        }
+      };
+      wait();
+      return;
+    }
+
+    const script = document.createElement('script');
+    script.src = `https://maps.googleapis.com/maps/api/js?key=${apiKey}&libraries=places`;
+    script.async = true;
+    script.defer = true;
+    script.setAttribute('data-sf-gmaps', 'true');
+    script.onload = () => {
+      this._googleAcService = new (window as any).google.maps.places.AutocompleteService();
+      this.locationMapLoaded = true;
+      setTimeout(() => this._renderMap(), 100);
+    };
+    document.head.appendChild(script);
+  }
+
+  onLocationTabChange(tab: string): void {
+    if (this.locationActiveTab === 'VENUE' && tab !== 'VENUE') {
+      this._googleMap = null;
+      this._mapMarkers = [];
+    }
+    this.locationActiveTab = tab;
+    this.locationSuggestions = [];
+    this.locationShowSuggestions = false;
+    this.locationSearchText = '';
+    const existing: LocationFieldValue = this.formGroup.get(this.config.name!)?.value || { tab, venues: [], onlineUrl: '' };
+    existing.tab = tab;
+    this.updateValue(existing);
+    if (tab === 'VENUE') {
+      setTimeout(() => this._renderMap());
+    }
+  }
+
+  get locationValue(): LocationFieldValue {
+    let v = this.formGroup.get(this.config.name!)?.value;
+    if (typeof v === 'string') {
+      try { v = JSON.parse(v); } catch { /* ignore */ }
+    }
+    // Automatically unwrap if prefill payload was mistakenly double-nested like `{ location: { tab... } }`
+    if (v && !v.tab && v[this.config.name!]) {
+      v = v[this.config.name!];
+    }
+    if (v && v.tab) return v;
+    return { tab: this.locationActiveTab, venues: [], onlineUrl: '' };
+  }
+
+  get locationVenues(): LocationItem[] {
+    return this.locationValue.venues || [];
+  }
+
+  get locationOnlineUrl(): string {
+    return this.locationValue.onlineUrl || '';
+  }
+
+  get locationMaxReached(): boolean {
+    const isMulti = this.config.locationConfig?.allowMulti;
+    const max = isMulti ? (this.config.locationConfig?.maxLocations ?? 5) : 1;
+    return this.locationVenues.length >= max;
+  }
+
+  handleLocationSearchInput(event: Event): void {
+    const input = (event.target as HTMLInputElement).value;
+    this.locationSearchText = input;
+    if (!input || input.length < 2) {
+      this.locationSuggestions = [];
+      this.locationShowSuggestions = false;
+      return;
+    }
+    if (!this._googleAcService) {
+      return;
+    }
+    this._googleAcService.getPlacePredictions({ input }, (predictions: any[], status: string) => {
+      if (status === 'OK' && predictions) {
+        this.locationSuggestions = predictions;
+        this.locationShowSuggestions = true;
+      } else {
+        this.locationSuggestions = [];
+        this.locationShowSuggestions = false;
+      }
+    });
+  }
+
+  onLocationSuggestionSelect(prediction: any): void {
+    if (!prediction) return;
+    const isMulti = this.config.locationConfig?.allowMulti;
+    const max = isMulti ? (this.config.locationConfig?.maxLocations ?? 5) : 1;
+    const current = this.locationVenues;
+    if (current.length >= max) return;
+
+    const newItem: LocationItem = {
+      description: prediction.description,
+      placeId: prediction.place_id,
+      address: prediction.description,
+      type: 'GOOGLE',
+      isActive: true
+    };
+
+    // Geocode to get lat/lng and components
+    if ((window as any).google?.maps?.Geocoder) {
+      const geocoder = new (window as any).google.maps.Geocoder();
+      geocoder.geocode({ placeId: prediction.place_id }, (results: any[], status: string) => {
+        if (status === 'OK' && results[0]) {
+          const res = results[0];
+          newItem.latitude = res.geometry?.location?.lat();
+          newItem.longitude = res.geometry?.location?.lng();
+          newItem.address = res.formatted_address || prediction.description;
+
+          let name = prediction.description;
+          if (prediction.structured_formatting && prediction.structured_formatting.main_text) {
+            name = prediction.structured_formatting.main_text;
+          }
+          newItem.name = name;
+
+          res.address_components?.forEach((c: any) => {
+            if (c.types.includes('locality')) newItem.cityLabel = c.long_name;
+            if (c.types.includes('administrative_area_level_1')) newItem.stateLabel = c.long_name;
+            if (c.types.includes('country')) newItem.countryLabel = c.long_name;
+          });
+        }
+        this._addVenueAndUpdate(newItem);
+      });
+    } else {
+      this._addVenueAndUpdate(newItem);
+    }
+
+    this.locationSearchText = '';
+    this.locationSuggestions = [];
+    this.locationShowSuggestions = false;
+  }
+
+  private _addVenueAndUpdate(item: LocationItem): void {
+    const val = { ...this.locationValue };
+    val.venues = [...(val.venues || []), item];
+    this.updateValue(val);
+    setTimeout(() => this._renderMap());
+  }
+
+  removeLocationVenue(index: number): void {
+    const val = { ...this.locationValue };
+    val.venues = (val.venues || []).filter((_, i) => i !== index);
+    this.updateValue(val);
+    setTimeout(() => this._renderMap());
+  }
+
+  onLocationUrlChange(url: string): void {
+    const val = { ...this.locationValue, onlineUrl: url };
+    this.updateValue(val);
+  }
+
+  hideLocationSuggestions(): void {
+    setTimeout(() => { this.locationShowSuggestions = false; }, 200);
+  }
+
+  getLocationMapEmbedUrl(): string {
+    const venues = this.locationVenues.filter(v => v.placeId || (typeof v.latitude === 'number' && typeof v.longitude === 'number'));
+    const apiKey = this.config.locationConfig?.googleMapsApiKey || '';
+
+    // No locations currently selected: Show the default map view (India)
+    if (!venues.length) {
+      if (apiKey) {
+        // Embed API center fallback if they have an API Key but no marker yet
+        const lat = this.config.locationConfig?.defaultLat ?? 20.5937;
+        const lng = this.config.locationConfig?.defaultLng ?? 78.9629;
+        const zoom = this.config.locationConfig?.defaultZoom ?? 4;
+        return `https://www.google.com/maps/embed/v1/view?key=${apiKey}&center=${lat},${lng}&zoom=${zoom}`;
+      } else {
+        // Static iframe fallback text query
+        return `https://maps.google.com/maps?q=India&output=embed`;
+      }
+    }
+
+    if (venues.length === 1) {
+      const v = venues[0];
+      const q = v.placeId ? `place_id:${v.placeId}` : encodeURIComponent(v.address || v.description || '');
+      return `https://www.google.com/maps/embed/v1/place?key=${apiKey}&q=${q}`;
+    }
+    // Multiple locations — use directions/search embed
+    const q = encodeURIComponent(venues.map(v => v.address || v.description).join('|'));
+    return `https://www.google.com/maps/embed/v1/search?key=${apiKey}&q=${q}`;
+  }
+
+  private _renderMap(): void {
+    if (!(window as any).google?.maps) return;
+    if (!this.config.locationConfig?.showMap && this.config.locationConfig?.showMap !== undefined) return;
+
+    const venues = this.locationVenues.filter(v => typeof v.latitude === 'number' && typeof v.longitude === 'number');
+
+    const mapEl = document.getElementById(`loc-map-${this.config.name}`);
+    if (!mapEl) return;
+
+    if (!this._googleMap) {
+      // Default to India if no venues exist
+      const defaultLat = this.config.locationConfig?.defaultLat ?? 20.5937;
+      const defaultLng = this.config.locationConfig?.defaultLng ?? 78.9629;
+      const defaultZoom = this.config.locationConfig?.defaultZoom ?? 4;
+
+      this._googleMap = new (window as any).google.maps.Map(mapEl, {
+        zoom: venues.length === 1 ? 12 : defaultZoom,
+        center: venues.length > 0
+          ? { lat: venues[0].latitude, lng: venues[0].longitude }
+          : { lat: defaultLat, lng: defaultLng }
+      });
+    } else {
+      if (venues.length === 0) {
+        // Re-center on default
+        const lat = this.config.locationConfig?.defaultLat ?? 20.5937;
+        const lng = this.config.locationConfig?.defaultLng ?? 78.9629;
+        this._googleMap.setCenter({ lat, lng });
+        this._googleMap.setZoom(this.config.locationConfig?.defaultZoom ?? 4);
+      } else if (venues.length === 1) {
+        this._googleMap.setCenter({ lat: venues[0].latitude, lng: venues[0].longitude });
+        this._googleMap.setZoom(12);
+      }
+    }
+
+    // Clear old markers
+    this._mapMarkers.forEach(m => m.setMap(null));
+    this._mapMarkers = [];
+
+    venues.forEach(v => {
+      const marker = new (window as any).google.maps.Marker({
+        position: { lat: v.latitude, lng: v.longitude },
+        map: this._googleMap,
+        title: v.name || v.address || v.description
+      });
+      this._mapMarkers.push(marker);
+    });
+
+    if (venues.length > 1) {
+      const bounds = new (window as any).google.maps.LatLngBounds();
+      venues.forEach(v => bounds.extend({ lat: v.latitude!, lng: v.longitude! }));
+      this._googleMap.fitBounds(bounds);
+    }
+  }
+}
+