@siliconst/metaui 1.4.51 → 2.0.0

package/src/nz/co/siliconst/ui5/metaui/controls/host/delegates/ValidationDelegate.ts

@@ -1,158 +1,318 @@
-import IllustratedMessage from "sap/m/IllustratedMessage";
-import Messaging from "sap/ui/core/Messaging";
-import Control from "sap/ui/core/Control";
-import { StateManager } from "../../../core/StateManager";
-import { Logger } from "../../../utils/Logger";
-import Message from "sap/ui/core/message/Message";
-import coreLibrary from "sap/ui/core/library";
-
-export interface IHostValidation {
-    getProperty(name: string): unknown;
-    setAggregation(aggregationName: string, object: Control, suppressInvalidate?: boolean): this;
-    getStateManager(): StateManager | null;
-}
-
-/**
- * Handles Fiori MessageManager integration and provides a standardized Error Boundary UI fallback.
- */
-export class ValidationDelegate {
-    private host: IHostValidation;
-
-    /**
-     * Initializes the ValidationDelegate for registering controls to the global MessageManager.
-     * @param host The parent host interface.
-     */
-    constructor(host: IHostValidation) {
-        this.host = host;
-    }
-
-    /**
-     * Registers a control and all its children with the global MessageManager.
-     * (Deprecated: Native registration causes UI5 to aggressively clear custom schema validation messages 
-     * on every keystroke. MetaUI handles valueState manually via plugins).
-     */
-    public registerObject(control: Control): void {
-        // Do nothing to prevent UI5 from hijacking valueState and clearing our manual messages
-    }
-
-    /**
-     * Unregisters a control from the global MessageManager.
-     */
-    public unregisterObject(control: Control): void {
-        // Do nothing
-    }
-
-    public removeAllMessages(): void {
-        const stateManager = this.host.getStateManager();
-        if (stateManager && this.host.getProperty("useMessageManager")) {
-            const messageManager = Messaging;
-            const messages = messageManager.getMessageModel().getData();
-            const messagesToRemove = messages.filter((m: Message) =>
-                m.getMessageProcessor() && m.getMessageProcessor().getId() === stateManager.getModel().getId()
-            );
-            if (messagesToRemove && messagesToRemove.length > 0) {
-                messageManager.removeMessages(messagesToRemove);
-            }
-        }
-    }
-
-    /**
-     * Pushes a validation message to the console, and optionally to the MessageManager.
-     * @param path The JSON pointer path of the field.
-     * @param text The error message.
-     * @param label The human-readable label of the field (optional).
-     */
-    public pushMessage(path: string, text: string, label?: string): void {
-        const targetPath = path ? `/${path.replace(/^\//, "")}` : "";
-        const displayLabel = label || path;
-        const displayText = path ? `Field '${displayLabel}': ${text}` : text;
-
-        if (path) {
-            Logger.warn(`[MetaUI Validation Error] ${displayText}`);
-        } else {
-            Logger.warn(`[MetaUI Validation Error] Global - ${text}`);
-        }
-
-        if (this.host.getProperty("useMessageManager") === true) {
-            const messageManager = Messaging;
-            const stateManager = this.host.getStateManager();
-            messageManager.addMessages(new Message({
-                message: displayText,
-                additionalText: displayLabel !== targetPath ? displayLabel : undefined,
-                type: coreLibrary.MessageType.Error,
-                target: targetPath,
-                processor: stateManager?.getModel()
-            }));
-        }
-    }
-
-    /**
-     * Imperatively invalidates a field and highlights it with an error message.
-     * Uses a specific 'CustomError' code to distinguish it from internal schema validations.
-     * 
-     * @param fieldPath The internal JSON path of the field to highlight.
-     * @param message The custom error message to display.
-     */
-    public addCustomError(fieldPath: string, message: string): void {
-        if (this.host.getProperty("useMessageManager") !== true) {
-            return;
-        }
-
-        const stateManager = this.host.getStateManager();
-        if (!stateManager) {
-            return;
-        }
-
-        Messaging.addMessages(new Message({
-            message: message,
-            type: coreLibrary.MessageType.Error,
-            target: `/${fieldPath.replace(/^\//, "")}`,
-            processor: stateManager.getModel(),
-            code: "CustomError"
-        }));
-    }
-
-    /**
-     * Reverts a custom error state on a field, safely ignoring native schema validations.
-     * 
-     * @param fieldPath The internal JSON path of the field to clear.
-     */
-    public clearCustomError(fieldPath: string): void {
-        if (this.host.getProperty("useMessageManager") !== true) {
-            return;
-        }
-
-        const stateManager = this.host.getStateManager();
-        if (!stateManager) {
-            return;
-        }
-
-        const target = `/${fieldPath.replace(/^\//, "")}`;
-        const processorId = stateManager.getModel().getId();
-        const messages = Messaging.getMessageModel().getData() as Message[];
-
-        const messagesToRemove = messages.filter(m =>
-            m.getTarget() === target &&
-            m.getCode() === "CustomError" &&
-            m.getMessageProcessor()?.getId() === processorId
-        );
-
-        if (messagesToRemove.length > 0) {
-            Messaging.removeMessages(messagesToRemove);
-        }
-    }
-
-    /**
-     * Triggers a visual Error Page (Crash Boundary) when generation catastrophically fails.
-     */
-    public mountCrashBoundary(error: Error): void {
-        Logger.error("[MetaUI] Engine failed to generate layout. Preventing Launchpad crash.", error.message, "ValidationDelegate");
-
-        const errorPage = new IllustratedMessage({
-            title: "UI Generation Failed",
-            description: "The dynamic schema could not be rendered. Please check the Fiori console for diagnostic logs."
-        });
-
-        this.host.setAggregation("_content", errorPage);
-    }
-}
+/**
+ * @file ValidationDelegate.ts
+ * @description Handles Fiori MessageManager integration and provides a standardized Error Boundary UI fallback.
+ */
+
+import IllustratedMessage from "sap/m/IllustratedMessage";
+import Messaging from "sap/ui/core/Messaging";
+import Control from "sap/ui/core/Control";
+import { StateManager } from "../../../core/StateManager";
+import { Engine } from "../../../core/Engine";
+import { IPluginValidationResult } from "../../../interfaces/IPlugin";
+import { Logger } from "../../../utils/Logger";
+import { OpenApiRefResolver } from "../../../openapi/OpenApiRefResolver";
+import { SchemaNormalizer } from "../../../core/SchemaNormalizer";
+import { isRecord } from "../../../utils/TypeGuards";
+import type { ISchema } from "../../../interfaces/ISchema";
+import Message from "sap/ui/core/message/Message";
+import MessageType from "sap/ui/core/message/MessageType";
+
+/**
+ * Host contract required by {@link ValidationDelegate} to manage validation state and error boundaries.
+ */
+export interface IHostValidation {
+    getProperty(name: string): unknown;
+    setProperty(name: string, value: unknown, suppressInvalidate?: boolean): unknown;
+    setAggregation(aggregationName: string, object: Control, suppressInvalidate?: boolean): this;
+    getStateManager(): StateManager | null;
+    fireEvent(eventId: string, parameters?: object): unknown;
+    addCustomError(fieldPath: string, message: string): void;
+    clearCustomError(fieldPath: string): void;
+}
+
+/**
+ * Handles Fiori MessageManager integration and provides a standardized Error Boundary UI fallback.
+ */
+export class ValidationDelegate {
+    private host: IHostValidation;
+    private readonly beforeSubmitErrorPaths: Set<string> = new Set();
+
+    /**
+     * Initializes the ValidationDelegate for publishing validation messages to the global MessageManager.
+     * @param host The parent host interface.
+     */
+    constructor(host: IHostValidation) {
+        this.host = host;
+    }
+
+    /**
+     * Normalizes an optional field key into the canonical event `fieldPath` contract:
+     * `""` when the event is whole-form / root (not tied to a specific field), or a
+     * leading-slash JSON Pointer (`"/..."`) when tied to a specific field.
+     *
+     * @param fieldKey Optional raw field key or JSON Pointer.
+     * @returns {string} Normalized `"/..."` pointer or `""`.
+     */
+    public static normalizeFieldPath(fieldKey?: string): string {
+        if (!fieldKey) {
+            return "";
+        }
+        const clean = fieldKey.replace(/^\/+/, "");
+        return clean ? `/${clean}` : "";
+    }
+
+    /**
+     * Removes non-custom validation messages owned by the host's StateManager from the global MessageManager.
+     * Custom errors (`code === "CustomError"`) are preserved until explicitly cleared via `clearCustomError`.
+     */
+    public removeAllMessages(): void {
+        const stateManager = this.host.getStateManager();
+        if (stateManager && this.host.getProperty("useMessageManager")) {
+            const messages: Message[] = Messaging.getMessageModel().getData();
+            const processorId = stateManager.getModel().getId();
+            const messagesToRemove = messages.filter((m: Message) =>
+                m.getMessageProcessor()?.getId() === processorId && m.getCode() !== "CustomError"
+            );
+            if (messagesToRemove.length > 0) {
+                Messaging.removeMessages(messagesToRemove);
+            }
+        }
+    }
+
+    /**
+     * Pushes a validation message to the console, and optionally to the MessageManager.
+     * @param path The JSON pointer path of the field.
+     * @param text The error message.
+     * @param label The human-readable label of the field (optional).
+     */
+    public pushMessage(path: string, text: string, label?: string): void {
+        const targetPath = ValidationDelegate.normalizeFieldPath(path);
+        const displayLabel = label || path;
+        const displayText = path ? `Field '${displayLabel}': ${text}` : text;
+
+        if (path) {
+            Logger.warn(`[MetaUI Validation Error] ${displayText}`);
+        } else {
+            Logger.warn(`[MetaUI Validation Error] Global - ${text}`);
+        }
+
+        if (this.host.getProperty("useMessageManager") === true) {
+            const stateManager = this.host.getStateManager();
+            Messaging.addMessages(new Message({
+                message: displayText,
+                additionalText: displayLabel !== targetPath ? displayLabel : undefined,
+                type: MessageType.Error,
+                target: targetPath,
+                processor: stateManager?.getModel()
+            }));
+        }
+    }
+
+    /**
+     * Imperatively invalidates a field in the global MessageManager when `useMessageManager` is active.
+     * Uses a specific `'CustomError'` code to distinguish it from internal schema validations.
+     *
+     * @param fieldPath The internal JSON path of the field to highlight.
+     * @param message The custom error message to display.
+     */
+    public addCustomError(fieldPath: string, message: string): void {
+        if (this.host.getProperty("useMessageManager") !== true) {
+            return;
+        }
+
+        const stateManager = this.host.getStateManager();
+        if (!stateManager) {
+            return;
+        }
+
+        this.clearCustomError(fieldPath);
+
+        Messaging.addMessages(new Message({
+            message: message,
+            type: MessageType.Error,
+            target: `/${fieldPath.replace(/^\//, "")}`,
+            processor: stateManager.getModel(),
+            code: "CustomError"
+        }));
+    }
+
+    /**
+     * Reverts a custom error state on a field in the global MessageManager.
+     *
+     * @param fieldPath The internal JSON path of the field to clear.
+     */
+    public clearCustomError(fieldPath: string): void {
+        if (this.host.getProperty("useMessageManager") !== true) {
+            return;
+        }
+
+        const stateManager = this.host.getStateManager();
+        if (!stateManager) {
+            return;
+        }
+
+        const target = `/${fieldPath.replace(/^\//, "")}`;
+        const processorId = stateManager.getModel().getId();
+        const messages = Messaging.getMessageModel().getData() as Message[];
+
+        const messagesToRemove = messages.filter(m =>
+            m.getTarget() === target &&
+            m.getCode() === "CustomError" &&
+            m.getMessageProcessor()?.getId() === processorId
+        );
+
+        if (messagesToRemove.length > 0) {
+            Messaging.removeMessages(messagesToRemove);
+        }
+    }
+
+    /**
+     * Triggers a visual Error Page (Crash Boundary) when generation catastrophically fails.
+     */
+    public mountCrashBoundary(error: Error): void {
+        Logger.error("[MetaUI] Engine failed to generate layout. Preventing Launchpad crash.", error.message, "ValidationDelegate");
+
+        const errorPage = new IllustratedMessage({
+            title: "UI Generation Failed",
+            description: "The dynamic schema could not be rendered. Please check the Fiori console for diagnostic logs."
+        });
+
+        this.host.setAggregation("_content", errorPage);
+    }
+
+    /**
+     * Publishes an array of field validation errors returned by `Engine.validateAll` to the `MessageManager`.
+     * @param errors The list of field validation errors.
+     */
+    public reportValidationErrors(errors: IPluginValidationResult[]): void {
+        if (this.host.getProperty("useMessageManager") === true) {
+            this.pushMessage(
+                "",
+                "One or more fields failed schema validation. Please review the highlighted fields."
+            );
+        }
+        const stateManager = this.host.getStateManager();
+        const processorId = stateManager?.getModel().getId();
+        const existingMsgs = (Messaging.getMessageModel().getData() as Message[]) || [];
+        for (const err of errors) {
+            if (err.fieldKey && err.errorMessage) {
+                const targetPath = `/${err.fieldKey.replace(/^\//, "")}`;
+                const alreadyExists =
+                    processorId !== undefined &&
+                    existingMsgs.some(
+                        (m) => m.getMessageProcessor()?.getId() === processorId && m.getTarget() === targetPath
+                    );
+                if (!alreadyExists) {
+                    this.pushMessage(err.fieldKey, err.errorMessage, err.fieldLabel);
+                }
+            }
+        }
+    }
+
+    /**
+     * Fires `validationStateChanged` and `validationError` / `validationSuccess` on a field validation change.
+     *
+     * @param isValid Whether the changed field passed validation.
+     * @param fieldKey The field path that changed.
+     * @param errorMessage Optional validation error message.
+     * @param overallIsValid Optional overall form validity computed from the `ValidationLedger`.
+     */
+    public notifyFieldValidation(
+        isValid: boolean,
+        fieldKey?: string,
+        errorMessage?: string,
+        overallIsValid?: boolean
+    ): void {
+        const effectiveFormValid = overallIsValid !== undefined ? overallIsValid : isValid;
+        if (effectiveFormValid !== (this.host.getProperty("isValid") as boolean)) {
+            this.host.setProperty("isValid", effectiveFormValid, true);
+            this.host.fireEvent("validationStateChanged", { isValid: effectiveFormValid });
+        }
+        this.host.fireEvent(isValid ? "validationSuccess" : "validationError", {
+            fieldPath: ValidationDelegate.normalizeFieldPath(fieldKey),
+            ...(isValid ? {} : { message: errorMessage || "Invalid input" })
+        });
+    }
+
+    /**
+     * Clears any custom errors previously registered by a `beforeSubmit` event handler via `addError`,
+     * without disturbing persistent custom errors registered via `host.addCustomError()`.
+     */
+    public clearBeforeSubmitErrors(): void {
+        if (this.beforeSubmitErrorPaths.size === 0) {
+            return;
+        }
+        for (const path of Array.from(this.beforeSubmitErrorPaths)) {
+            this.host.clearCustomError(path);
+        }
+        this.beforeSubmitErrorPaths.clear();
+    }
+
+    /**
+     * Fires `beforeSubmit` and returns true if the consumer did not call `preventDefault()` or `addError()`.
+     * @param payload The extracted clean payload.
+     * @returns {boolean} True if submission may proceed.
+     */
+    public confirmBeforeSubmit(payload: unknown): boolean {
+        this.clearBeforeSubmitErrors();
+        let isPrevented = false;
+        this.host.fireEvent("beforeSubmit", {
+            payload,
+            preventDefault: () => {
+                isPrevented = true;
+            },
+            addError: (propertyPath: string, errorMessage: string) => {
+                isPrevented = true;
+                this.beforeSubmitErrorPaths.add(propertyPath);
+                this.host.addCustomError(propertyPath, errorMessage);
+            }
+        });
+        return !isPrevented;
+    }
+
+    /**
+     * Resolves a `$ref` path against normalized definitions or lazily normalizes the host's `schemaDefinitions`.
+     * @param refPath The `$ref` path string.
+     * @param cachedDefs Optional cached definitions map.
+     * @returns {{ definition: ISchema | undefined; normalizedDefs: Record<string, ISchema> | undefined }}
+     */
+    public resolveDefinition(
+        refPath: string,
+        cachedDefs?: Record<string, ISchema>
+    ): { definition: ISchema | undefined; normalizedDefs: Record<string, ISchema> | undefined } {
+        let defs = cachedDefs;
+        if (!defs) {
+            const rawDefs = this.host.getProperty("schemaDefinitions");
+            if (isRecord(rawDefs)) {
+                defs = {};
+                for (const key of Object.keys(rawDefs)) {
+                    defs[key] = SchemaNormalizer.normalizeDefinition(rawDefs[key], key);
+                }
+            }
+        }
+        if (!defs || !refPath) {
+            return { definition: undefined, normalizedDefs: defs };
+        }
+        const key = OpenApiRefResolver.extractRefName(refPath);
+        return { definition: defs[key], normalizedDefs: defs };
+    }
+
+    /**
+     * Collects diagnostic DOM metadata from the active Engine plugins.
+     * @param engine The active Engine instance, if any.
+     * @returns {Record<string, unknown>[]} Array of `{ path, controlId }` descriptors.
+     */
+    public collectDebugDomMetadata(engine: Engine | null): Record<string, unknown>[] {
+        if (!engine) return [];
+        return engine.getActivePlugins().map((entry) => ({
+            path: entry.path,
+            controlId:
+                typeof entry.plugin.getControlId === "function"
+                    ? entry.plugin.getControlId()
+                    : typeof entry.plugin.getFieldLabel === "function"
+                      ? entry.plugin.getFieldLabel()
+                      : entry.path,
+            label: typeof entry.plugin.getFieldLabel === "function" ? entry.plugin.getFieldLabel() : entry.path
+        }));
+    }
+}