@siliconst/metaui 1.4.44 → 2.0.0

package/src/nz/co/siliconst/ui5/metaui/plugins/controls/ReferencePlugin.ts

@@ -1,212 +1,77 @@
-/**
- * @file ReferencePlugin.ts
- * @description Renders a button that lazily loads a referenced schema definition from the global dictionary
- * and opens it in a nested dialog. Implements headless validation for the deferred schema.
- */
-
-import { BasePlugin } from "./BasePlugin";
-import { IPluginValidationResult } from "../../interfaces/IPlugin";
-import { UI5_EVENT, UI5_AGGREGATION } from "../../constants/MetaUIConstants";
-import { ISchema, IPropertyMetadata } from "../../interfaces/ISchema";
-import Control from "sap/ui/core/Control";
-import Event from "sap/ui/base/Event";
-import Button from "sap/m/Button";
-import JSONModel from "sap/ui/model/json/JSONModel";
-import { GlobalPipeline } from "../../core/PipelineManager";
-import { Logger } from "../../utils/Logger";
-
-export class ReferencePlugin extends BasePlugin {
-    /**
-     * Interface for the duck-typed parent GeneratorHost.
-     */
-    private _asHost(control: Control): { getSchemaDefinition(ref: string): ISchema; getProperty(name: string): unknown; fireEvent(name: string, params?: unknown): void; } | null {
-        const host = control as unknown as { getSchemaDefinition?: Function; getProperty?: Function; fireEvent?: Function; };
-        if (typeof host.getSchemaDefinition === "function") {
-            return host as { getSchemaDefinition(ref: string): ISchema; getProperty(name: string): unknown; fireEvent(name: string, params?: unknown): void; };
-        }
-        return null;
-    }
-
-    /**
-     * Finds the closest GeneratorHost in the control hierarchy.
-     */
-    private findParentHost(control: Control): unknown {
-        let parent = control.getParent();
-        while (parent) {
-            if (this._asHost(parent)) {
-                return parent;
-            }
-            parent = parent.getParent();
-        }
-        return null;
-    }
-
-    public render(field: IPropertyMetadata, bindingPath: string, modelName: string = "meta", engineScopeId?: string, onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void): Control {
-        this.onChange = onChange;
-        this.metadata = field;
-        const propKey = bindingPath.startsWith("/") ? bindingPath.substring(1) : bindingPath;
-        const label = field.ui?.label || propKey;
-
-        this.control = new Button({
-            id: this.generateStableId(engineScopeId, bindingPath),
-            text: !this.isEditable ? `View Link: ${label}` : `Edit Link: ${label}`,
-            icon: "sap-icon://chain-link",
-            press: (oEvent: Event) => {
-                const btn = oEvent.getSource() as Button;
-                if (!this.metadata?.$ref) {
-                    Logger.error(`[ReferencePlugin] FATAL: this.metadata.$ref is MISSING or UNDEFINED! Cannot resolve child schema.`);
-                    return;
-                }
-                
-                const rawParentHost = this.findParentHost(btn) as Control;
-                const parentHost = rawParentHost ? this._asHost(rawParentHost) : null;
-                if (!parentHost) {
-                    Logger.error("[ReferencePlugin] FATAL: Could not locate parent GeneratorHost via duck typing `getSchemaDefinition`.");
-                    return;
-                }
-
-                const subSchema = parentHost.getSchemaDefinition(this.metadata.$ref);
-                if (!subSchema) {
-                    const keys = Object.keys(parentHost.getProperty("schemaDefinitions") || {});
-                    Logger.error(`[ReferencePlugin] FATAL: Schema definition not found for reference: ${this.metadata.$ref}. Dumping parent schemaDefinitions keys: ${keys.join(", ")}`);
-                    return;
-                }
-
-                const parentModel = btn.getModel(modelName) as JSONModel;
-                if (!parentModel) {
-                    Logger.error(`[ReferencePlugin] FATAL: Could not get JSONModel named '${modelName}' from the button.`);
-                    return;
-                }
-                
-                const bindingContext = btn.getBindingContext(modelName);
-                let updatePath = bindingPath;
-                if (bindingContext && !bindingPath.startsWith("/")) {
-                    const ctxPath = bindingContext.getPath();
-                    updatePath = ctxPath.endsWith("/") ? ctxPath + bindingPath : (ctxPath === "/" ? "/" + bindingPath : ctxPath + "/" + bindingPath);
-                }
-                
-                const rawData = parentModel.getProperty(updatePath);
-                const nestedData = rawData ? JSON.parse(JSON.stringify(rawData)) : {};
-
-                sap.ui.require(["nz/co/siliconst/ui5/metaui/controls/DynamicHost"], (DynamicHostModule: unknown) => {
-                    const DynamicHostClass = (DynamicHostModule as any).default || DynamicHostModule;
-                    const host = new DynamicHostClass({
-                        schemaDefinition: subSchema,
-                        schemaDefinitions: parentHost.getProperty("schemaDefinitions"), // Pass the dictionary down
-                        data: nestedData,
-                        editable: this.isEditable,
-                        useMessageManager: this.useMessageManager
-                    });
-
-                    // Event Piping: Bubble validation events up to the parent host
-                    host.attachEvent("validationError", (e: Event) => {
-                        parentHost.fireEvent("validationError", e.getParameters());
-                    });
-                    host.attachEvent("validationSuccess", (e: Event) => {
-                        parentHost.fireEvent("validationSuccess", e.getParameters());
-                    });
-
-                    if (!!this.isEditable) {
-                        host.attachEvent(UI5_EVENT.SUBMIT, (e: Event) => {
-                            const payload = (e.getParameter("payload") as unknown);
-                            parentModel.setProperty(updatePath, payload);
-                            
-                            if (this.onChange) {
-                                this.onChange(true, propKey);
-                            }
-                        });
-                    }
-
-                    const buttonText = field.ui?.dialogButtonText || (!this.isEditable ? "Close" : "OK");
-                    try {
-                        host.openInDialog(`Nested Link: ${label}`, buttonText, undefined, undefined, btn);
-                    } catch (e) {
-                        Logger.error(`[ReferencePlugin] FATAL ERROR CALLING openInDialog:`, (e as Error).message);
-                    }
-                });
-            }
-        });
-
-        return this.control as Control;
-    }
-
-    /**
-     * Headless validation: since child controls are not rendered, we manually validate the nested payload against the lazily resolved schema.
-     */
-    public validate(): IPluginValidationResult {
-        if (!this.metadata?.$ref || !this.control) return { isValid: true };
-        
-        const rawParentHost = this.findParentHost(this.control) as Control;
-        const parentHost = rawParentHost ? this._asHost(rawParentHost) : null;
-        if (!parentHost) return { isValid: true };
-        
-        const subSchema = parentHost.getSchemaDefinition(this.metadata.$ref);
-        if (!subSchema || !subSchema.properties) return { isValid: true };
-        
-        const parentModel = this.control.getModel(this.modelName) as JSONModel;
-        if (!parentModel) return { isValid: true };
-        
-        let updatePath = this.getAbsoluteBindingPath();
-        
-        const nestedData = parentModel.getProperty(updatePath) || {};
-        
-        // Basic headless validation over the subSchema properties
-        for (const key of Object.keys(subSchema.properties)) {
-            const propMeta = subSchema.properties[key] as IPropertyMetadata;
-            const val = nestedData[key];
-            
-            if (propMeta.required && (val === undefined || val === null || val === "")) {
-                const errMsg = `Field '${key}' is required in referenced object.`;
-                this.setVisualValidationState(false, errMsg);
-                return { isValid: false, errorMessage: errMsg };
-            }
-            
-            const validatorsToRun: string[] = [];
-            const argsMap: Record<string, unknown> = {};
-
-            if (propMeta.maxLength !== undefined) {
-                validatorsToRun.push("maxLength");
-                argsMap["maxLength"] = propMeta.maxLength;
-            }
-            if (propMeta.minLength !== undefined) {
-                validatorsToRun.push("minLength");
-                argsMap["minLength"] = propMeta.minLength;
-            }
-            if (propMeta.pattern !== undefined) {
-                validatorsToRun.push("pattern");
-                argsMap["pattern"] = { regex: propMeta.pattern };
-            }
-            if (propMeta.minimum !== undefined || propMeta.maximum !== undefined) {
-                validatorsToRun.push("range");
-                argsMap["range"] = { min: propMeta.minimum, max: propMeta.maximum };
-            }
-            
-            const format = propMeta.ui?.format;
-            if (format === "email" || format === "url" || format === "iban") {
-                validatorsToRun.push(format);
-            }
-            
-            if (validatorsToRun.length > 0) {
-                const res = GlobalPipeline.executeValidation(val, validatorsToRun, argsMap);
-                if (!res.isValid) {
-                    const errMsg = `Field '${key}' in reference: ${res.errorMessage}`;
-                    this.setVisualValidationState(false, errMsg);
-                    return { isValid: false, errorMessage: errMsg };
-                }
-            }
-        }
-        
-        this.setVisualValidationState(true);
-        return { isValid: true };
-    }
-
-    protected getValue(): null {
-        return null;
-    }
-
-    protected applyState(): void {
-        if (this.control && this.metadata) {
-            (this.control as Button).setEnabled(!this.metadata.ui?.readOnly);
-        }
-    }
-}
+/**
+ * @file ReferencePlugin.ts
+ * @description Renders a button that resolves a $ref schema definition and opens a modal DynamicHost dialog.
+ */
+
+import { INestedDialogDescriptor, NestedDialogPlugin } from "./NestedDialogPlugin";
+import { IPropertyMetadata, ISchema } from "../../interfaces/ISchema";
+import { OpenApiRefResolver } from "../../openapi/OpenApiRefResolver";
+import { Logger } from "../../utils/Logger";
+import { I18n, MetaUITextKey, TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Plugin responsible for rendering `$ref` schema reference triggers (`sap.m.Button`).
+ * Resolves the target schema definition from the owning `Engine` context and opens a modal `DynamicHost` dialog.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export class ReferencePlugin extends NestedDialogPlugin {
+    protected readonly defaultErrorTooltipKey: MetaUITextKey = TEXT_KEY.nestedReferenceInvalid;
+    protected readonly emptyFallbackValue: unknown = null;
+
+    /**
+     * Resolves the default button label from `metadata.ui.label` or the `$ref` tail segment.
+     *
+     * @param metadata The property metadata.
+     * @returns {string} The button label stem.
+     */
+    protected getDefaultLabel(metadata: IPropertyMetadata): string {
+        const refName = metadata.$ref ? OpenApiRefResolver.extractRefName(metadata.$ref) : "";
+        return metadata.ui?.label || refName || I18n.getText(TEXT_KEY.nestedReferenceLabel);
+    }
+
+    /**
+     * Resolves the chain-link icon for the reference trigger button.
+     *
+     * @param _canEdit Unused editability flag.
+     * @returns {string} The SAP icon URI.
+     */
+    protected getButtonIcon(_canEdit: boolean): string {
+        return "sap-icon://chain-link";
+    }
+
+    /**
+     * Resolves `metadata.$ref` via the owning `Engine` context and builds the modal dialog descriptor.
+     *
+     * @param metadata The reference property metadata containing `$ref`.
+     * @returns {INestedDialogDescriptor | null} The resolved dialog descriptor, or `null` if `$ref` is missing/unresolved.
+     */
+    protected buildDialogDescriptor(metadata: IPropertyMetadata): INestedDialogDescriptor | null {
+        if (!metadata.$ref) {
+            Logger.error("[MetaUI ReferencePlugin] Missing '$ref' on reference property.", "", "ReferencePlugin");
+            return null;
+        }
+
+        const resolvedSchema: ISchema | null = this.engineContext?.getSchemaDefinition(metadata.$ref) ?? null;
+        if (!resolvedSchema) {
+            Logger.error(
+                `[MetaUI ReferencePlugin] Could not resolve schema definition for '${metadata.$ref}'.`,
+                "",
+                "ReferencePlugin"
+            );
+            return null;
+        }
+
+        const title =
+            metadata.ui?.label ||
+            resolvedSchema.title ||
+            OpenApiRefResolver.extractRefName(metadata.$ref) ||
+            I18n.getText(TEXT_KEY.nestedReferenceLabel);
+        return {
+            title,
+            subSchema: { ...resolvedSchema, ui: this.buildSubSchemaUi(metadata, resolvedSchema.ui) },
+            isArrayRoot: resolvedSchema.type === "array"
+        };
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/controls/RichTextPlugin.ts

@@ -1,84 +1,43 @@
-import { BasePlugin } from "../controls/BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import Control from "sap/ui/core/Control";
-import RichTextControl from "../../controls/RichTextControl";
-import FormattedTextControl from "sap/m/FormattedText";
-
-interface IValueAccessor {
-    getValue(): unknown;
-    attachCapture?(fn: Function): void;
-}
-
-function isValueAccessor(control: unknown): control is IValueAccessor {
-    return control !== null && typeof (control as IValueAccessor).getValue === 'function';
-}
-
-export class RichTextPlugin extends BasePlugin {
-    /**
-     * Renders a `RichTextControl` component.
-     * 
-     * @param metadata The specific JSON schema properties for this field.
-     * @param bindingPath The JSON path bound to this control.
-     * @param modelName The UI5 JSONModel name.
-     * @param engineScopeId The deterministic scope ID.
-     * @param onChange The callback fired on value change.
-     * @returns {Control} The configured RichTextControl.
-     */
-    public render(metadata: IPropertyMetadata,  bindingPath: string,  modelName: string = "meta", engineScopeId?: string, onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void): Control {
-        this.onChange = onChange;
-        this.metadata = metadata;
-        this.fieldKey = bindingPath.replace('/', '');
-        this.modelName = modelName;
-
-        if (!this.isEditable) {
-            
-            this.control = new FormattedTextControl({
-                id: this.generateStableId(engineScopeId, bindingPath),
-                htmlText: this.generateBindingInfo(bindingPath, modelName)
-            }) as Control;
-            this.applyCommonDirectives(this.control, metadata, modelName);
-            return this.control as Control;
-        }
-
-        this.control = new RichTextControl({
-            id: this.generateStableId(engineScopeId, bindingPath),
-            value: this.generateBindingInfo(bindingPath, modelName),
-            schemaMetadata: metadata,
-            readOnly: !!metadata.ui?.readOnly
-        }) as Control;
-
-        this.applyCommonDirectives(this.control, metadata, modelName);
-
-        if (isValueAccessor(this.control) && this.control.attachCapture) {
-            this.control.attachEvent('capture', () => {
-                const result = this.validate();
-                if (this.onChange) {
-                    this.onChange(result.isValid, this.fieldKey, result.errorMessage);
-                }
-            });
-        }
-
-        return this.control as Control;
-    }
-
-    /**
-     * Retrieves the current HTML string value.
-     * @returns {unknown} The string value.
-     */
-    protected getValue(): unknown {
-        if (isValueAccessor(this.control)) {
-            return this.control.getProperty('value');
-        }
-        return null;
-    }
-
-    /**
-     * Applies dynamic read-only state.
-     */
-    protected applyState(): void {
-        if (this.control && this.metadata) {
-            if (!this.isEditable) return;
-            (this.control as sap.ui.core.Control).setProperty("readOnly", !!this.metadata.ui?.readOnly);
-        }
-    }
-}
+/**
+ * @file RichTextPlugin.ts
+ * @description Renders a RichTextControl component in edit mode and a FormattedText in display mode.
+ */
+
+import { HardwareControlPlugin } from "./HardwareControlPlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import Control from "sap/ui/core/Control";
+import RichTextControl from "../../controls/RichTextControl";
+import FormattedTextControl from "sap/m/FormattedText";
+
+/**
+ * Plugin responsible for rendering the `RichTextControl` WYSIWYG HTML editor.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export class RichTextPlugin extends HardwareControlPlugin<RichTextControl> {
+    protected readonly HardwareControlClass = RichTextControl;
+
+    /**
+     * Renders a `sap.m.FormattedText` control in display mode.
+     *
+     * @param metadata The property metadata.
+     * @param bindingPath The JSON path bound to this control.
+     * @param modelName The UI5 JSONModel name.
+     * @param engineScopeId The deterministic scope ID.
+     * @returns {Control} The configured FormattedText control.
+     */
+    protected renderDisplayControl(
+        metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string,
+        engineScopeId?: string
+    ): Control {
+        this.control = new FormattedTextControl({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            htmlText: this.generateBindingInfo(bindingPath, modelName) as unknown as string
+        });
+        this.applyCommonDirectives(this.control, metadata, modelName);
+        return this.control;
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/controls/SignaturePlugin.ts

@@ -1,72 +1,38 @@
-import { BasePlugin } from "../controls/BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import Control from "sap/ui/core/Control";
-import SignatureControl from "../../controls/SignatureControl";
-import ImageControl from "sap/m/Image";
-
-export class SignaturePlugin extends BasePlugin {
-    /**
-     * Renders a `SignatureControl` component.
-     * 
-     * @param metadata The specific JSON schema properties for this field.
-     * @param bindingPath The JSON path bound to this control.
-     * @param modelName The UI5 JSONModel name.
-     * @param engineScopeId The deterministic scope ID.
-     * @param onChange The callback fired on value change.
-     * @returns {Control} The configured SignatureControl.
-     */
-    public render(metadata: IPropertyMetadata,  bindingPath: string,  modelName: string = "meta", engineScopeId?: string, onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void): Control {
-        this.onChange = onChange;
-        this.metadata = metadata;
-        this.fieldKey = bindingPath.replace('/', '');
-        this.modelName = modelName;
-
-        if (!this.isEditable) {
-            
-            this.control = new ImageControl({
-                id: this.generateStableId(engineScopeId, bindingPath),
-                src: this.generateBindingInfo(bindingPath, modelName),
-                width: "400px",
-                alt: metadata.ui?.label || "Signature"
-            }) as Control;
-            this.applyCommonDirectives(this.control, metadata, modelName);
-            return this.control as Control;
-        }
-
-        this.control = new SignatureControl({
-            id: this.generateStableId(engineScopeId, bindingPath),
-            value: this.generateBindingInfo(bindingPath, modelName),
-            schemaMetadata: metadata,
-            readOnly: !!metadata.ui?.readOnly
-        }) as Control;
-
-        this.applyCommonDirectives(this.control, metadata, modelName);
-
-        (this.control as SignatureControl).attachEvent('capture', () => {
-            const result = this.validate();
-                if (this.onChange) {
-                    this.onChange(result.isValid, this.fieldKey, result.errorMessage);
-                }
-        });
-
-        return this.control as Control;
-    }
-
-    /**
-     * Retrieves the current base64 signature image state.
-     * @returns {unknown} The signature image value.
-     */
-    protected getValue(): unknown {
-        return this.control ? (this.control as SignatureControl).getProperty('value') : null;
-    }
-
-    /**
-     * Applies dynamic read-only state.
-     */
-    protected applyState(): void {
-        if (this.control && this.metadata) {
-            if (!this.isEditable) return;
-            (this.control as sap.ui.core.Control).setProperty("readOnly", !!this.metadata.ui?.readOnly);
-        }
-    }
-}
+/**
+ * @file SignaturePlugin.ts
+ * @description Renders a SignatureControl component in edit mode and an Image in display mode.
+ */
+
+import { HardwareControlPlugin } from "./HardwareControlPlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import Control from "sap/ui/core/Control";
+import SignatureControl from "../../controls/SignatureControl";
+import { I18n, TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Plugin responsible for rendering the hardware `SignatureControl` canvas pad.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export class SignaturePlugin extends HardwareControlPlugin<SignatureControl> {
+    protected readonly HardwareControlClass = SignatureControl;
+
+    /**
+     * Renders a URL-validated `sap.m.Image` in display mode.
+     *
+     * @param metadata The property metadata.
+     * @param bindingPath The JSON path bound to this control.
+     * @param modelName The UI5 JSONModel name.
+     * @param engineScopeId The deterministic scope ID.
+     * @returns {Control} The configured Image control.
+     */
+    protected renderDisplayControl(
+        metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string,
+        engineScopeId?: string
+    ): Control {
+        return this.renderSafeImageDisplay(metadata, bindingPath, modelName, engineScopeId, I18n.getText(TEXT_KEY.hardwareSignatureAlt));
+    }
+}