platformcommons-web-lib 1.0.0

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

@@ -0,0 +1,1087 @@
+import { ChangeDetectorRef, Component, EventEmitter, Input, OnDestroy, OnInit, OnChanges, SimpleChanges, Output } from '@angular/core';
+import { FormArray, FormBuilder, FormGroup } from '@angular/forms';
+import { HttpClient, HttpHeaders } from '@angular/common/http';
+import { Router } from '@angular/router';
+import { ActionBarConfig, ActionButtonConfig, ActionConfig, FieldConfig, FormSchema } from '../../models/form-schema.model';
+import { HierarchyCfg } from '../../models/hierarchy-config.model';
+import { SmartFormController } from '../../services/smart-form-controller.service';
+import { ExpressionService } from '../../services/expression.service';
+import { SmartFormTranslationUtils } from '../../utils/translation.utils';
+import { SnackbarService } from '../../../snackbar/services/snackbar.service';
+import { Subject, takeUntil, forkJoin, Observable, of } from 'rxjs';
+import { catchError, map } from 'rxjs/operators';
+
+@Component({
+  selector: 'lib-smart-form',
+  templateUrl: './smart-form.component.html',
+  styleUrls: ['./smart-form.component.scss'],
+  providers: [SmartFormController],
+  standalone: false
+})
+export class SmartFormComponent implements OnInit, OnChanges, OnDestroy {
+  private destroy$ = new Subject<void>();
+  @Input() formJson!: string;
+  @Input() initialValues?: { [key: string]: any };
+  @Input() enableDraftAutoSave: boolean = false;
+  /** Flat i18n labels map passed by the consuming app.
+   *  After JSON parse the schema is walked and every string value that
+   *  matches a key in this map is replaced with the translated value.
+   *  Mirrors the pattern used by ConfigurableFormComponent + translateConfig.
+   */
+  @Input() labels: any = {};
+  @Input() mode: 'CREATE' | 'EDIT' = 'CREATE';
+  /** When true, all form fields are disabled and the action bar is hidden (preview/read-only mode). */
+  @Input() readOnly: boolean = false;
+
+  @Output() submit = new EventEmitter<{ [key: string]: any }>();
+  @Output() draftSave = new EventEmitter<string>();
+  /**
+   * Emitted when a button with a custom `type` (not 'cancel', 'draft', or
+   * 'submit') is clicked. Payload contains the button `id` and the current
+   * form data snapshot.
+   */
+  @Output() actionClick = new EventEmitter<{ id: string; formData: { [key: string]: any } }>();
+  @Output() valueChange = new EventEmitter<{ [key: string]: any }>();
+  @Output() fileAdded = new EventEmitter<any>();
+  @Output() fileUploadFinished = new EventEmitter<any>();
+  @Output() fileRemoved = new EventEmitter<any>();
+  /** Emitted when a suffixActionIcon is clicked. Payload: { fieldName, actionId } */
+  @Output() suffixActionClick = new EventEmitter<{ fieldName: string; actionId: string }>();
+  /** Emitted whenever the active section step changes. Carries current state so the
+   *  host can show/hide Previous/Next/Submit buttons in its own footer. */
+  @Output() stepChange = new EventEmitter<{
+    currentStep: number;
+    totalSteps: number;
+    isFirst: boolean;
+    isLast: boolean;
+    stepLabel: string;
+  }>();
+
+  formSchema!: FormSchema;
+  formGroup!: FormGroup;
+  fieldList: FieldConfig[] = [];
+  isStepper: boolean = false;
+  currentStep: number = 0;
+  isLoading: boolean = false;
+  isDraftLoading: boolean = false;
+
+  /** True when sectionStepper mode is active (SECTION form with top-level GROUPs as steps). */
+  isSectionStepper: boolean = false;
+  /** Index of the currently visible section step. */
+  currentSectionStep: number = 0;
+  /** Flat list of top-level GROUP FieldConfigs that become the stepper steps. */
+  sectionSteps: FieldConfig[] = [];
+  /** Validation state per section step — drives badge colour/icon. */
+  stepValidationStates: ('untouched' | 'valid' | 'warning')[] = [];
+  /** Flat field-name lists per step used for targeted validation. */
+  private stepFieldNames: string[][] = [];
+
+  /** Controls skeleton visibility. Stays false until schema is parsed AND
+   *  any EDIT-mode data fetch completes, but always shows for at least
+   *  SKELETON_MIN_MS so the animation is visible even on fast loads. */
+  isFormReady = false;
+  private readonly SKELETON_MIN_MS = 350;
+  private _skeletonStart = 0;
+
+  constructor(
+    private fb: FormBuilder,
+    public controller: SmartFormController,
+    private expressionService: ExpressionService,
+    private http: HttpClient,
+    private snackbarService: SnackbarService,
+    private router: Router,
+    private cdr: ChangeDetectorRef
+  ) { }
+
+  ngOnInit(): void {
+    this._skeletonStart = Date.now();
+    this._startForm();
+    this.controller.fileAdded$.pipe(takeUntil(this.destroy$)).subscribe(file => this.fileAdded.emit(file));
+    this.controller.fileUploadFinished$.pipe(takeUntil(this.destroy$)).subscribe(file => this.fileUploadFinished.emit(file));
+    this.controller.fileRemoved$.pipe(takeUntil(this.destroy$)).subscribe(file => this.fileRemoved.emit(file));
+    this.controller.suffixActionClick$.pipe(takeUntil(this.destroy$)).subscribe(data => this.suffixActionClick.emit(data));
+  }
+
+  loadEditData(): void {
+    const config = this.formSchema.editConfig!;
+    this.isLoading = true;
+    const headers = this.getHeaders();
+    this.http.get(config.loadApiUrl, { headers }).subscribe({
+      next: (response: any) => {
+        this.initialValues = response;
+        this.controller.initialize(this.initialValues || {});
+        this.isLoading = false;
+        this._markReady();
+      },
+      error: (err) => {
+        this.showAlert('error', config.errorMessage || 'Failed to load form data', config.snackbarConfig);
+        console.error('Load data error:', err);
+        this.isLoading = false;
+        this._markReady();
+      }
+    });
+  }
+
+  /** Flips isFormReady=true after the skeleton has been visible for at least SKELETON_MIN_MS. */
+  private _markReady(): void {
+    const elapsed = Date.now() - this._skeletonStart;
+    const remaining = Math.max(0, this.SKELETON_MIN_MS - elapsed);
+    setTimeout(() => {
+      this.isFormReady = true;
+      // markForCheck propagates dirty up through any OnPush ancestor components
+      // (e.g. configurator-config-panel) so the skeleton-to-form transition
+      // renders in the same zone tick rather than waiting for a future user event.
+      this.cdr.markForCheck();
+    }, remaining);
+  }
+
+  ngOnChanges(changes: SimpleChanges): void {
+    if (changes['formJson'] && !changes['formJson'].isFirstChange()) {
+      this._startForm();
+    }
+    if (changes['labels'] && !changes['labels'].isFirstChange() && this.formSchema) {
+      this._startForm();
+    }
+  }
+
+  ngOnDestroy(): void {
+    this.controller.destroy();
+    this.destroy$.next();
+    this.destroy$.complete();
+  }
+
+  /** Public backward-compatible entry point — delegates to _startForm. */
+  parseFormJson(): void {
+    this._startForm();
+  }
+
+  private _startForm(): void {
+    if (!this.formJson) return;
+    let schema: any;
+    try {
+      schema = JSON.parse(this.formJson);
+    } catch (e) {
+      console.error('SmartForm: invalid formJson', e);
+      return;
+    }
+    if (this._hasHierarchyDynamic(schema)) {
+      this._expandHierarchyNodes(schema)
+        .pipe(takeUntil(this.destroy$))
+        .subscribe({
+          next: expanded => this._applySchema(expanded),
+          error: () => this._applySchema(schema),
+        });
+    } else {
+      this._applySchema(schema);
+    }
+  }
+
+  private _applySchema(schema: any): void {
+    this.formSchema = schema as FormSchema;
+    this.controller.token = this.formSchema.token;
+    this.controller.tokenHeader = this.formSchema.tokenHeader;
+    if (this.labels && Object.keys(this.labels).length) {
+      SmartFormTranslationUtils.translateSchema(this.formSchema, this.labels);
+    }
+    this.controller.labels = this.labels;
+    this.controller.actionLabels = this.formSchema.labels;
+    this.isStepper = this.formSchema.formType === 'STEPPER';
+    this.fieldList = this.isStepper
+      ? (this.formSchema.stepperConfig?.children || []).filter(step => step.isEnabled !== false && step.sectionConfig?.isEnabled !== false)
+      : (this.formSchema.sectionConfig?.children || []).filter(field => field.isEnabled !== false);
+    const topLevelGroups = this.fieldList.filter(f => f.type === 'GROUP' && f.sectionConfig);
+    this.isSectionStepper = !this.isStepper &&
+      (this.formSchema.sectionStepper === true ||
+        (this.formSchema.sectionStepper !== false && topLevelGroups.length === this.fieldList.length && topLevelGroups.length > 1));
+    if (this.isSectionStepper) {
+      this.sectionSteps = topLevelGroups;
+      this.currentSectionStep = 0;
+      this.stepValidationStates = this.sectionSteps.map(() => 'untouched' as const);
+      this.stepFieldNames = this.sectionSteps.map(s => this._collectFieldNames(s.sectionConfig?.children || []));
+      setTimeout(() => this._emitStepChange());
+    }
+    // Pre-seed array values (allowMulti GROUP initial data) into the controller
+    // BEFORE initializeForm() runs. form-field.initGroupField() calls
+    // controller.getFieldValue(groupKey) during ngOnInit to determine how many
+    // rows to create — it must find the array already there or it falls back to
+    // a single empty row and loses all initial values.
+    if (this.initialValues) {
+      Object.entries(this.initialValues).forEach(([key, value]) => {
+        if (Array.isArray(value)) {
+          this.controller.updateField(key, value);
+        }
+      });
+    }
+    this.initializeForm();
+    if (this.mode === 'EDIT' && this.formSchema?.editConfig?.loadApiUrl) {
+      this.loadEditData();
+    } else if (this.initialValues) {
+      this.controller.initialize(this.initialValues);
+      this._markReady();
+    } else {
+      this._markReady();
+    }
+  }
+
+
+  initializeForm(): void {
+    this.formGroup = this.fb.group({});
+    this.collectFields(this.fieldList);
+
+    // In read-only mode, disable all controls so the form acts as a preview
+    if (this.readOnly) {
+      this.formGroup.disable();
+    }
+
+    // Emit value changes to parent (skipped in read-only mode)
+    if (!this.readOnly) {
+      this.formGroup.valueChanges.pipe(takeUntil(this.destroy$)).subscribe(() => {
+        this.valueChange.emit(this.collectFormData());
+      });
+    }
+  }
+
+  collectFields(fields: FieldConfig[]): void {
+    fields.forEach(field => {
+      if (field.isEnabled === false || field.sectionConfig?.isEnabled === false) return;
+
+      // Flat leaf fields: seed controller with default values
+      if (field.name && field.type !== 'GROUP' && field.type !== 'ROW') {
+        // Check if initialValues already has a value for this field
+        const existingValue = this.initialValues?.[field.name];
+        const value = existingValue !== undefined
+          ? existingValue
+          : (field.defaultValue !== undefined ? field.defaultValue : null);
+        this.controller.updateField(field.name, value);
+      }
+      // Recurse into ROW children
+      if (field.type === 'ROW' && field.children?.length) {
+        this.collectFields(field.children);
+      }
+      // Recurse into GROUP children
+      if (field.type === 'GROUP' && field.sectionConfig?.children?.length) {
+        this.collectFields(field.sectionConfig.children);
+      }
+    });
+  }
+
+  // ───────────────────────────────────────────────────────────────────────────
+  // Submit
+  // ───────────────────────────────────────────────────────────────────────────
+
+  handleSubmit(): void {
+    if (this.isStepper && this.currentStep < this.fieldList.length - 1) {
+      if (this.validate()) this.nextStep();
+      return;
+    }
+    if (!this.validate()) return;
+
+    this.submitToApi(this.collectFormData(), 'submit');
+  }
+
+  // ───────────────────────────────────────────────────────────────────────────
+  // Cancel
+  // ───────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Universal action handler for any button click.
+   * One handler decides how to process based on action.kind.
+   */
+  handleButtonClick(btn: ActionButtonConfig): void {
+    const action = btn.action;
+    if (!action) return;
+
+    switch (action.kind) {
+      case 'submit':
+        this.handleSubmit();
+        break;
+      case 'draft':
+        this.submitToApi(this.collectFormData(), 'draft', btn);
+        break;
+      case 'navigate':
+        this.navigateTo(action.redirectUrl);
+        break;
+      case 'api':
+        this.fireActionApiCall(action);
+        break;
+      case 'emit':
+        this.actionClick.emit({ id: btn.id, formData: this.collectFormData() });
+        break;
+      case 'next':
+        if (this.validate()) this.nextStep();
+        break;
+      case 'prev':
+        this.previousStep();
+        break;
+    }
+  }
+
+  // ── Action-Redirects & API ──────────────────────────────────────────────────
+
+  private fireActionApiCall(action: ActionConfig): void {
+    if (!action.apiUrl) return;
+    const headers = this.getHeaders();
+    const method = action.method || 'POST';
+    const body = action.extraPayload || {};
+
+    this.isLoading = true;
+    this.http.request(method, action.apiUrl, { body, headers }).subscribe({
+      next: (response) => {
+        this.isLoading = false;
+        const msg = action.successMessage || 'Action successful';
+        this.showAlert('success', msg, action.snackbarConfig);
+        if (action.redirectUrl) this.navigateTo(action.redirectUrl);
+      },
+      error: (err) => {
+        this.isLoading = false;
+        const msg = action.errorMessage || 'Action failed';
+        this.showAlert('error', msg, action.snackbarConfig);
+        console.error('API Action error:', err);
+      }
+    });
+  }
+
+  /**
+   * Constructs nested payload by checking field properties on form controls.
+   */
+  collectFormData(): { [key: string]: any } {
+    const rawValue = this.extractGroupValue(this.formGroup);
+    let payload = this.buildNestedPayload(rawValue, this.fieldList);
+
+    // Merge extra fields based on the mode
+    const config = this.mode === 'EDIT' ? this.formSchema.editConfig : this.formSchema.submitConfig;
+    if (config?.extraPayload) {
+      payload = this.deepMerge(payload, config.extraPayload);
+    }
+
+    return payload;
+  }
+
+  /**
+   * Deep merges the source object (e.g. extraPayload) into the target object (e.g. form payload).
+   */
+  private deepMerge(target: any, source: any): any {
+    if (typeof target !== 'object' || target === null) {
+      return source;
+    }
+    if (typeof source !== 'object' || source === null) {
+      return source;
+    }
+
+    if (Array.isArray(target) && Array.isArray(source)) {
+      // For arrays, we merge objects at the same index
+      const maxLength = Math.max(target.length, source.length);
+      const mergedArray = [];
+      for (let i = 0; i < maxLength; i++) {
+        if (i < target.length && i < source.length) {
+          mergedArray.push(this.deepMerge(target[i], source[i]));
+        } else if (i < source.length) {
+          mergedArray.push(source[i]);
+        } else {
+          mergedArray.push(target[i]);
+        }
+      }
+      return mergedArray;
+    }
+
+    const merged = { ...target };
+    Object.keys(source).forEach(key => {
+      if (source[key] instanceof Object && key in target) {
+        merged[key] = this.deepMerge(target[key], source[key]);
+      } else {
+        merged[key] = source[key];
+      }
+    });
+    return merged;
+  }
+
+  private buildNestedPayload(rawValue: any, fields: FieldConfig[]): { [key: string]: any } {
+    if (rawValue === null || typeof rawValue !== 'object') return rawValue;
+
+    const payload: { [key: string]: any } = {};
+    const processedKeys = new Set<string>();
+
+    const processFields = (fieldList: FieldConfig[]) => {
+      fieldList.forEach(field => {
+        if (field.isEnabled === false || field.sectionConfig?.isEnabled === false) return;
+
+        if (field.type === 'ROW' && field.children) {
+          processFields(field.children);
+        } else if (field.type === 'GROUP' && field.sectionConfig?.children) {
+          // FormFieldComponent generates unnamed groups using their label inside the root FormGroup.
+          const generatedKey = field.sectionConfig.label
+            ? field.sectionConfig.label.replace(/(?:^\w|[A-Z]|\b\w)/g, (w, i) => i === 0 ? w.toLowerCase() : w.toUpperCase()).replace(/\s+/g, '')
+            : '';
+          const groupKey = field.sectionConfig.name || field.name || generatedKey || '__group__';
+          
+          processedKeys.add(groupKey);
+
+          const groupRawValue = rawValue[groupKey];
+          if (groupRawValue !== undefined) {
+            // Identify if it's purely a visual section vs an explicit structural data block
+            const isStructural = field.sectionConfig.name || field.name || field.sectionConfig.allowMulti;
+
+            if (!isStructural) {
+              // Visual section: Flatten its contents directly onto the target payload layer
+              Object.assign(payload, this.buildNestedPayload(groupRawValue, field.sectionConfig.children));
+            } else {
+              // Structural block: process nested mappings / array instances
+              const nestedData = (field.sectionConfig.allowMulti && Array.isArray(groupRawValue))
+                ? groupRawValue.map(item => this.buildNestedPayload(item, field.sectionConfig!.children!))
+                : this.buildNestedPayload(groupRawValue, field.sectionConfig.children);
+
+              if (field.payloadPath) {
+                this.setNestedValue(payload, field.payloadPath, nestedData);
+              } else {
+                payload[groupKey] = nestedData;
+              }
+            }
+          }
+        } else if (field.name) {
+          processedKeys.add(field.name);
+          if (rawValue[field.name] !== undefined) {
+            const val = rawValue[field.name];
+            if (field.payloadPath) {
+              this.setNestedValue(payload, field.payloadPath, val);
+            } else {
+              payload[field.name] = val;
+            }
+          }
+        }
+      });
+    };
+
+    processFields(fields);
+
+    // Preserve any hidden tracking keys (e.g. id, uuid, isEdit) that were present in the initial data
+    Object.keys(rawValue).forEach(key => {
+      if (!processedKeys.has(key)) {
+        payload[key] = rawValue[key];
+      }
+    });
+
+    return payload;
+  }
+
+  private setNestedValue(obj: any, path: string, value: any): void {
+    // Regex matches the property name and optionally an array index e.g. "name[0]" -> regex yields ["name[0]", "name", "0"]
+    const arrayRegex = /^([a-zA-Z0-9_]+)\[(\d+)\]$/;
+
+    const parts = path.split('.');
+    let current = obj;
+
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      const match = part.match(arrayRegex);
+
+      if (match) {
+        const prop = match[1];
+        const index = parseInt(match[2], 10);
+        if (!current[prop]) current[prop] = [];
+        if (!current[prop][index]) current[prop][index] = {};
+        current = current[prop][index];
+      } else {
+        if (!current[part]) current[part] = {};
+        current = current[part];
+      }
+    }
+
+    const lastPart = parts[parts.length - 1];
+    const matchLast = lastPart.match(arrayRegex);
+    if (matchLast) {
+      const prop = matchLast[1];
+      const index = parseInt(matchLast[2], 10);
+      if (!current[prop]) current[prop] = [];
+      current[prop][index] = value;
+    } else {
+      current[lastPart] = value;
+    }
+  }
+
+  private extractGroupValue(group: FormGroup): { [key: string]: any } {
+    const result: { [key: string]: any } = {};
+    Object.keys(group.controls).forEach(key => {
+      const ctrl = group.controls[key];
+      if (ctrl instanceof FormArray) {
+        // Repeater → array of objects
+        result[key] = (ctrl.controls as FormGroup[]).map(fg => this.extractGroupValue(fg));
+      } else if (ctrl instanceof FormGroup) {
+        // Nested single group → nested object
+        result[key] = this.extractGroupValue(ctrl);
+      } else {
+        result[key] = ctrl?.value ?? null;
+      }
+    });
+    return result;
+  }
+
+  validate(): boolean {
+    if (this.formGroup.invalid) {
+      this.formGroup.markAllAsTouched();
+      this.scrollToFirstInvalidControl();
+      return false;
+    }
+    return true;
+  }
+
+  scrollToFirstInvalidControl(): void {
+    setTimeout(() => {
+      // .is-invalid is set by form-field on actual control elements (not on <form>).
+      // The fallback targets native inputs/selects directly so we never accidentally
+      // scroll to the <form> element, which also receives .ng-invalid.ng-touched.
+      const firstInvalidControl =
+        document.querySelector('.is-invalid') ||
+        document.querySelector(
+          'input.ng-invalid.ng-touched, select.ng-invalid.ng-touched, textarea.ng-invalid.ng-touched'
+        );
+      if (firstInvalidControl) {
+        firstInvalidControl.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      }
+    }, 100);
+  }
+
+  submitToApi(formData: any, actionType: 'submit' | 'draft' = 'submit', btn?: ActionButtonConfig): void {
+    const isEdit = this.mode === 'EDIT';
+    const configLine: any = isEdit ? this.formSchema.editConfig : this.formSchema.submitConfig;
+    const action = btn?.action;
+
+    // Build the final payload, merging draft extraPayload if applicable
+    let finalPayload = formData;
+    if (actionType === 'draft' && action?.extraPayload) {
+      finalPayload = this.deepMerge(finalPayload, action.extraPayload);
+    }
+
+    // Fallback for emitted outputs if no API URL is defined centrally
+    if (!configLine || (!configLine.apiUrl && !configLine.submitApiUrl)) {
+      if (actionType === 'draft') {
+        this.draftSave.emit(JSON.stringify(finalPayload));
+        if (action?.redirectUrl) this.navigateTo(action.redirectUrl);
+      } else {
+        this.submit.emit(finalPayload);
+      }
+      return;
+    }
+
+    const apiUrl = isEdit ? configLine.submitApiUrl : configLine.apiUrl;
+    const method = isEdit ? (configLine.submitMethod || 'PATCH') : (configLine.method || 'POST');
+    const headers = this.getHeaders();
+
+    // Messages and redirect URLs (Prefer button action overrides if present)
+    const successMsg = actionType === 'draft'
+      ? (action?.successMessage || 'Draft saved successfully')
+      : (action?.successMessage || configLine.successMessage || 'Form submitted successfully');
+
+    const errorMsg = actionType === 'draft'
+      ? (action?.errorMessage || 'Failed to save draft')
+      : (action?.errorMessage || configLine.errorMessage || 'Failed to submit form');
+
+    const redirectUrl = actionType === 'draft'
+      ? (action?.redirectUrl || configLine.redirectUrl)
+      : (action?.redirectUrl || configLine.redirectUrl);
+
+    if (actionType === 'draft') {
+      this.isDraftLoading = true;
+    } else {
+      this.isLoading = true;
+    }
+
+    this.http.request(method, apiUrl, { body: finalPayload, headers }).subscribe({
+      next: (response) => {
+        this.showAlert('success', successMsg, action?.snackbarConfig || configLine.snackbarConfig);
+
+        if (actionType === 'draft') {
+          this.draftSave.emit(JSON.stringify(response));
+          this.isDraftLoading = false;
+        } else {
+          this.submit.emit(response);
+          this.isLoading = false;
+        }
+
+        if (redirectUrl) {
+          setTimeout(() => this.navigateTo(redirectUrl), 1500);
+        }
+      },
+      error: (err) => {
+        this.showAlert('error', errorMsg, action?.snackbarConfig || configLine.snackbarConfig);
+        console.error(actionType === 'draft' ? 'Draft save error:' : 'Submit error:', err);
+        this.isLoading = false;
+        this.isDraftLoading = false;
+      }
+    });
+  }
+
+  showAlert(type: 'success' | 'error' | 'warning' | 'info', message: string, customConfig?: any): void {
+    this.snackbarService.show({
+      variant: type,
+      message: message,
+      showCloseButton: true,
+      ...customConfig
+    });
+  }
+
+  /** Builds HttpHeaders from the token stored in the controller (sourced from configJSON). */
+  getHeaders(): HttpHeaders {
+    let headers = new HttpHeaders();
+    if (this.controller.token) {
+      const headerName = this.controller.tokenHeader || 'Authorization';
+      headers = headers.set(headerName, this.controller.token);
+    }
+    return headers;
+  }
+
+  // ───────────────────────────────────────────────────────────────────────────
+  // Stepper
+  // ───────────────────────────────────────────────────────────────────────────
+
+  nextStep(): void {
+    if (this.currentStep < this.fieldList.length - 1) this.currentStep++;
+  }
+
+  previousStep(): void {
+    if (this.currentStep > 0) this.currentStep--;
+  }
+
+  get canGoNext(): boolean { return this.currentStep < this.fieldList.length - 1; }
+  get canGoPrevious(): boolean { return this.currentStep > 0; }
+  get currentStepConfig(): FieldConfig | undefined {
+    return this.isStepper ? this.fieldList[this.currentStep] : undefined;
+  }
+
+  // ── Section Stepper (public API called by host via ViewChild) ────────────────
+
+  /** Advance to the next section step. Called by the host footer "Next" button.
+   *  Validates the current step first — marks it valid (green) or warning (orange). */
+  navigateToNext(): void {
+    if (!this.isSectionStepper) return;
+    if (this.currentSectionStep < this.sectionSteps.length - 1) {
+      this._validateStep(this.currentSectionStep);
+      this.currentSectionStep++;
+      this._emitStepChange();
+    }
+  }
+
+  /** Go back to the previous section step. Called by the host footer "Previous" button. */
+  navigateToPrevious(): void {
+    if (!this.isSectionStepper) return;
+    if (this.currentSectionStep > 0) {
+      this.currentSectionStep--;
+      this._emitStepChange();
+    }
+  }
+
+  /** Jump directly to a specific section step by index.
+   *  Validates the step being left so the badge state updates correctly. */
+  goToSectionStep(index: number): void {
+    if (!this.isSectionStepper) return;
+    if (index < 0 || index >= this.sectionSteps.length || index === this.currentSectionStep) return;
+    this._validateStep(this.currentSectionStep);
+    this.currentSectionStep = index;
+    this._emitStepChange();
+  }
+
+  get isSectionStepFirst(): boolean { return this.currentSectionStep === 0; }
+  get isSectionStepLast(): boolean { return this.currentSectionStep === this.sectionSteps.length - 1; }
+
+  /** Returns the SectionConfig for a given step — passed to lib-form-section.
+   *  The outer label is intentionally omitted because the stepper nav already
+   *  displays it; showing it again inside the content would be redundant. */
+  getSectionStepConfig(step: FieldConfig): any {
+    const { label, ...rest } = step.sectionConfig! as any;
+    return rest;
+  }
+
+  private _emitStepChange(): void {
+    const step = this.sectionSteps[this.currentSectionStep];
+    this.stepChange.emit({
+      currentStep: this.currentSectionStep,
+      totalSteps: this.sectionSteps.length,
+      isFirst: this.isSectionStepFirst,
+      isLast: this.isSectionStepLast,
+      stepLabel: step?.sectionConfig?.label || `Step ${this.currentSectionStep + 1}`
+    });
+  }
+
+  /** Marks all controls in the given step as touched and records valid/warning state. */
+  private _validateStep(stepIndex: number): void {
+    const names = this.stepFieldNames[stepIndex] || [];
+    let hasInvalid = false;
+    names.forEach(name => {
+      const ctrl = this.formGroup.get(name);
+      if (!ctrl) return;
+      if (ctrl instanceof FormArray) {
+        ctrl.controls.forEach(c => c.markAllAsTouched());
+        if (ctrl.invalid) hasInvalid = true;
+      } else if (ctrl instanceof FormGroup) {
+        ctrl.markAllAsTouched();
+        if (ctrl.invalid) hasInvalid = true;
+      } else {
+        ctrl.markAsTouched();
+        if (ctrl.invalid) hasInvalid = true;
+      }
+    });
+    this.stepValidationStates[stepIndex] = hasInvalid ? 'warning' : 'valid';
+  }
+
+  /** Recursively collects all leaf field names from a set of FieldConfigs. */
+  private _collectFieldNames(fields: FieldConfig[]): string[] {
+    const names: string[] = [];
+    fields.forEach(f => {
+      if (f.isEnabled === false) return;
+      if (f.name && f.type !== 'GROUP' && f.type !== 'ROW') {
+        names.push(f.name);
+      }
+      if (f.type === 'ROW' && f.children?.length) {
+        names.push(...this._collectFieldNames(f.children));
+      }
+      if (f.type === 'GROUP' && f.sectionConfig?.children?.length) {
+        if (f.name || f.sectionConfig.name) {
+          names.push((f.name || f.sectionConfig.name)!);
+        }
+        names.push(...this._collectFieldNames(f.sectionConfig.children));
+      }
+    });
+    return names;
+  }
+
+  // ── Action Labels ──────────────────────────────────────────────────────────
+
+  get nextLabel(): string {
+    const key = this.formSchema?.labels?.nextLabel || 'Next';
+    return this.labels[key] || key;
+  }
+
+  get submitLabel(): string {
+    const btn = this.getButtonByActionKind('submit');
+    if (btn?.label) return this.labels[btn.label] || btn.label;
+    const key = this.formSchema?.labels?.submitLabel || 'Submit';
+    return this.labels[key] || key;
+  }
+
+  get previousLabel(): string {
+    const key = this.formSchema?.labels?.previousLabel || 'Previous';
+    return this.labels[key] || key;
+  }
+
+  // ── Action Bar helpers ─────────────────────────────────────────────────────
+
+  get actionBarConfig(): ActionBarConfig | undefined {
+    return this.formSchema?.actionBarConfig;
+  }
+
+  /**
+   * Returns buttons for a given alignment, sorted by `order` (stable).
+   */
+  getButtonsForAlignment(alignment: 'left' | 'right'): ActionButtonConfig[] {
+    return (this.actionBarConfig?.buttons || [])
+      .filter(b => !b.hidden && (b.alignment ?? 'right') === alignment)
+      .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  }
+
+  getButtonLabel(btn: ActionButtonConfig): string {
+    if (btn.action?.kind === 'submit' && this.isStepper && this.canGoNext) {
+      return this.nextLabel;
+    }
+    const key = btn.label || btn.id;
+    return this.labels[key] || key;
+  }
+
+  isButtonDisabled(btn: ActionButtonConfig): boolean {
+    if (btn.disabled) return true;
+    const kind = btn.action?.kind;
+    if (kind === 'submit' || kind === 'draft' || kind === 'api') {
+      return this.isLoading || this.isDraftLoading;
+    }
+    return false;
+  }
+
+  private getButtonByActionKind(kind: string): ActionButtonConfig | undefined {
+    return (this.actionBarConfig?.buttons || []).find(b => b.action?.kind === kind);
+  }
+
+  // ── Navigation helper ──────────────────────────────────────────────────────
+
+  private navigateTo(url?: string): void {
+    if (!url) return;
+    if (url.startsWith('http://') || url.startsWith('https://')) {
+      window.location.href = url;
+    } else {
+      this.router.navigateByUrl(url);
+    }
+  }
+
+  // ── GEOGRAPHY_DYNAMIC / Hierarchy expansion ───────────────────────────────
+  // Supports any API-driven hierarchy template.  All paths, URLs, field names
+  // and dependency params are driven entirely by the geographyConfig JSON node —
+  // nothing is hardcoded here.  New deployments only need to update the JSON.
+
+  private _hasHierarchyDynamic(obj: any): boolean {
+    if (!obj || typeof obj !== 'object') return false;
+    if ((obj as any)['type'] === 'GEOGRAPHY_DYNAMIC') return true;
+    return Object.values(obj as object).some((v: any) => this._hasHierarchyDynamic(v));
+  }
+
+  private _expandHierarchyNodes(schema: any): Observable<any> {
+    return this._expandNodeRecursive(schema);
+  }
+
+  private _expandNodeRecursive(obj: any): Observable<any> {
+    if (!this._hasHierarchyDynamic(obj)) return of(obj);
+
+    if (Array.isArray(obj)) {
+      const tasks$: Observable<any[]>[] = (obj as any[]).map((item: any) => {
+        if (item && (item as any)['type'] === 'GEOGRAPHY_DYNAMIC') {
+          return this._expandSingleNode(item);
+        }
+        return this._expandNodeRecursive(item).pipe(map((v: any) => [v]));
+      });
+      return (tasks$.length > 0 ? forkJoin(tasks$) : of([] as any[][])).pipe(
+        map((arrays: any[][]) => ([] as any[]).concat(...arrays))
+      );
+    }
+
+    if (typeof obj === 'object' && obj !== null) {
+      const keysWithDynamic = Object.keys(obj as object).filter(k =>
+        this._hasHierarchyDynamic((obj as any)[k])
+      );
+      if (keysWithDynamic.length === 0) return of(obj);
+      const updates$ = keysWithDynamic.map(key =>
+        this._expandNodeRecursive((obj as any)[key]).pipe(map((v: any) => ({ key, value: v })))
+      );
+      return forkJoin(updates$).pipe(
+        map((updates: { key: string; value: any }[]) => {
+          const result: any = { ...(obj as object) };
+          updates.forEach(u => { result[u.key] = u.value; });
+          return result;
+        })
+      );
+    }
+
+    return of(obj);
+  }
+
+  private _expandSingleNode(node: any): Observable<any[]> {
+    const rawCfg = (node as any)['geographyConfig'] || (node as any)['hierarchyConfig'];
+    if (!rawCfg) return of([]);
+    const cfg = this._normalizeHierarchyCfg(rawCfg);
+    if (!cfg.templateApiUrl) return of([]);
+    return this._fetchHierarchyTemplate(cfg).pipe(
+      map((template: any) => template ? this._buildHierarchyFields(cfg, template) : []),
+      catchError(() => of([]))
+    );
+  }
+
+  private _normalizeHierarchyCfg(raw: any): HierarchyCfg {
+    // New nested format: templateApi / dataApi / structure / field sub-objects
+    if (raw['templateApi'] && typeof raw['templateApi'] === 'object') {
+      const ta = raw['templateApi'];
+      const da = raw['dataApi'] || {};
+      const st = raw['structure'] || {};
+      const fi = raw['field'] || {};
+      return {
+        templateApiUrl: ta['apiUrl'] || ta['url'] || '',
+        templateListPath: ta['listPath'] ?? null,
+        templateSelect: ta['select'] || 'default',
+        templateSelectField: ta['selectField'] || 'isDefault',
+        templateSelectCode: ta['selectCode'],
+        rootCodePath: st['rootCodePath'] || 'rootClassCode',
+        templateCodePath: st['templateCodePath'] || 'templateCode',
+        hierarchyListPath: st['hierarchyListPath'] || 'mdmclasshierarchytemplatestructList',
+        parentField: st['parentField'] || 'parentCode',
+        childField: st['childField'] || 'childCode',
+        dataApiUrl: da['apiUrl'] || da['url'] || '',
+        dataPath: da['dataPath'] || 'elements',
+        labelPath: da['labelPath'] || 'name[0].text',
+        valuePath: da['valuePath'] || 'code',
+        colSpan: fi['colSpan'] ?? 12,
+        payloadPrefix: fi['payloadPathPrefix'] || '',
+        dependencyParam: fi['dependency']?.['paramName'] || 'parentDataCode',
+        nodes: fi['nodes'] || {},
+        branchSubType: fi['branchSubType'] || 'SINGLE',
+      };
+    }
+    // Legacy flat format (backward compatibility with existing geographyConfig JSON)
+    const reqCodes: string[] = raw['requiredClassCodes'] || [];
+    const payloadMap: Record<string, string> = raw['classCodePayloadFieldMap'] || {};
+    const nodes: Record<string, any> = {};
+    [...new Set([...reqCodes, ...Object.keys(payloadMap)])].forEach(code => {
+      nodes[code] = { payloadField: payloadMap[code], required: reqCodes.includes(code) };
+    });
+    return {
+      templateApiUrl: raw['templateApiUrl'] || '',
+      templateListPath: null,
+      templateSelect: raw['useDefault'] !== false ? 'default' : 'first',
+      templateSelectField: 'isDefault',
+      rootCodePath: 'rootClassCode',
+      templateCodePath: 'templateCode',
+      hierarchyListPath: 'mdmclasshierarchytemplatestructList',
+      parentField: 'parentCode',
+      childField: 'childCode',
+      dataApiUrl: raw['dataApiUrl'] || '',
+      dataPath: raw['dataPath'] || 'elements',
+      labelPath: raw['labelPath'] || 'name[0].text',
+      valuePath: raw['valuePath'] || 'code',
+      colSpan: raw['colSpan'] ?? 12,
+      payloadPrefix: raw['payloadPathPrefix'] || '',
+      dependencyParam: 'parentDataCode',
+      nodes,
+      branchSubType: 'SINGLE',
+    };
+  }
+
+  private _fetchHierarchyTemplate(cfg: HierarchyCfg): Observable<any> {
+    const headers = this.getHeaders();
+    return this.http.get<any>(cfg.templateApiUrl, { headers }).pipe(
+      map((response: any) => {
+        let list: any[];
+        if (cfg.templateListPath) {
+          list = this._getPathValue(response, cfg.templateListPath) || [];
+        } else if (Array.isArray(response)) {
+          list = response;
+        } else {
+          list = [response];
+        }
+        if (!Array.isArray(list) || list.length === 0) return null;
+        if (cfg.templateSelect === 'first') return list[0];
+        if (cfg.templateSelect === 'byCode') {
+          return list.find((t: any) => this._getPathValue(t, cfg.templateCodePath) === cfg.templateSelectCode) || list[0];
+        }
+        return list.find((t: any) => !!t[cfg.templateSelectField]) || list[0];
+      }),
+      catchError(() => of(null))
+    );
+  }
+
+  private _buildHierarchyFields(cfg: HierarchyCfg, template: any): any[] {
+    const rootCode: string = this._getPathValue(template, cfg.rootCodePath) || '';
+    const templateCode: string = this._getPathValue(template, cfg.templateCodePath) || '';
+    const hierList: any[] = this._getPathValue(template, cfg.hierarchyListPath) || [];
+
+    const childrenMap = new Map<string, string[]>();
+    hierList.forEach((s: any) => {
+      const parent = s[cfg.parentField];
+      const child = s[cfg.childField];
+      if (parent != null && child != null) {
+        if (!childrenMap.has(parent)) childrenMap.set(parent, []);
+        childrenMap.get(parent)!.push(child);
+      }
+    });
+
+    const fields: any[] = [];
+
+    const buildField = (code: string, parentFieldName: string | null, visibilityExpression?: string): void => {
+      const nodeOvr: any = cfg.nodes[code] || {};
+
+      if (nodeOvr['hidden']) {
+        (childrenMap.get(code) || []).forEach(c => buildField(c, parentFieldName, visibilityExpression));
+        return;
+      }
+
+      const fieldName: string = nodeOvr['name'] || this._codeToFieldName(code);
+      const label: string = nodeOvr['label'] || this._codeToLabel(code);
+      const payloadField: string = nodeOvr['payloadField'] || fieldName;
+      const colSpan: number = nodeOvr['colSpan'] ?? cfg.colSpan;
+      const payloadPath: string = cfg.payloadPrefix ? `${cfg.payloadPrefix}.${payloadField}` : payloadField;
+
+      const apiUrl: string = (cfg.dataApiUrl || '')
+        .replace(/\{classCode\}/g, encodeURIComponent(code))
+        .replace(/\{templateCode\}/g, encodeURIComponent(templateCode));
+
+      const optionConfig: any = {
+        apiUrl,
+        dataPath: cfg.dataPath,
+        labelPath: cfg.labelPath,
+        valuePath: cfg.valuePath,
+      };
+      if (parentFieldName && !nodeOvr['noDependency']) {
+        optionConfig['dependencies'] = { [cfg.dependencyParam]: parentFieldName };
+      }
+
+      const fieldDef: any = {
+        name: fieldName,
+        label,
+        payloadPath,
+        type: 'DROPDOWN',
+        subType: 'SINGLE',
+        colSpan,
+        isEnabled: true,
+        optionConfig,
+      };
+      if (visibilityExpression) fieldDef['visibilityExpression'] = visibilityExpression;
+      if (nodeOvr['required']) {
+        fieldDef['required'] = true;
+        fieldDef['errorMessage'] = nodeOvr['errorMessage'] || `Please select ${label.toLowerCase()}`;
+      }
+      if (nodeOvr['placeholder']) fieldDef['placeholder'] = nodeOvr['placeholder'];
+
+      fields.push(fieldDef);
+
+      const children = childrenMap.get(code) || [];
+      if (children.length > 1) {
+        // Branch point: dynamically build Area Type selector from children
+        const branchOptions = children.map(c => {
+          const childOvr: any = cfg.nodes[c] || {};
+          const childFieldName = childOvr['name'] || this._codeToFieldName(c);
+          const childLabel = childOvr['label'] || this._codeToLabel(c);
+          return { label: childLabel, code: childFieldName };
+        });
+
+        const areaTypeField: any = {
+          name: 'areaType',
+          label: 'Area Type',
+          type: 'DROPDOWN',
+          subType: cfg.branchSubType,
+          colSpan,
+          isEnabled: true,
+          optionConfig: { optionList: branchOptions },
+        };
+        if (visibilityExpression) areaTypeField['visibilityExpression'] = visibilityExpression;
+        fields.push(areaTypeField);
+
+        // Skip structural branch-type nodes (e.g. RURAL, URABN) — they carry no MDM data.
+        // Walk their descendants with `fieldName` (the linear parent before the fork, e.g. State)
+        // as the dependency, so the first real data level loads correctly.
+        children.forEach(c => {
+          const childOvr: any = cfg.nodes[c] || {};
+          const childFieldName = childOvr['name'] || this._codeToFieldName(c);
+          const branchVisExpr = `areaType === '${childFieldName}'`;
+          const branchDescendants = childrenMap.get(c) || [];
+          if (branchDescendants.length === 0) {
+            // Unusual: branch-type node has no descendants — fall back to treating it as a data field
+            buildField(c, fieldName, branchVisExpr);
+          } else {
+            // Skip the branch-type node; walk its children with the pre-fork parent as dependency
+            branchDescendants.forEach(desc => buildField(desc, fieldName, branchVisExpr));
+          }
+        });
+      } else {
+        children.forEach(c => buildField(c, fieldName, visibilityExpression));
+      }
+    };
+
+    buildField(rootCode, null);
+    return fields;
+  }
+
+  private _getPathValue(obj: any, path: string): any {
+    if (!path || obj == null) return obj;
+    return path.split('.').reduce((curr: any, key: string) => {
+      if (curr == null) return undefined;
+      const m = key.match(/^(\w+)\[(\d+)\]$/);
+      return m ? curr[m[1]]?.[Number(m[2])] : curr[key];
+    }, obj);
+  }
+
+  private _codeToFieldName(classCode: string): string {
+    const suffix = (classCode.split('.').pop() || classCode).replace(/^REGION_/, '');
+    const words = suffix.split('_');
+    if (words.length === 0) return classCode.toLowerCase();
+    return words[0].toLowerCase() +
+      words.slice(1).map((w: string) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
+  }
+
+  private _codeToLabel(classCode: string): string {
+    const suffix = (classCode.split('.').pop() || classCode).replace(/^REGION_/, '');
+    return suffix.split('_').map((w: string) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(' ');
+  }
+
+}