@siliconst/metaui 1.4.44 → 2.0.0

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

@@ -1,72 +1,51 @@
-import { BasePlugin } from "../controls/BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import Control from "sap/ui/core/Control";
-import GeolocationControl from "../../controls/GeolocationControl";
-import TextControl from "sap/m/Text";
-
-export class GeolocationPlugin extends BasePlugin {
-    /**
-     * Renders a `GeolocationControl` 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 GeolocationControl.
-     */
-    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 TextControl({
-                id: this.generateStableId(engineScopeId, bindingPath),
-                text: this.generateBindingInfo(bindingPath, modelName, undefined, {
-                    formatter: (val: Record<string, unknown>) => val && val.lat !== undefined && val.lng !== undefined ? `Lat: ${val.lat}, Lng: ${val.lng}` : ""
-                })
-            });
-            this.applyCommonDirectives(this.control, metadata, modelName);
-            return this.control as Control;
-        }
-
-        this.control = new GeolocationControl({
-            id: this.generateStableId(engineScopeId, bindingPath),
-            value: this.generateBindingInfo(bindingPath, modelName),
-            schemaMetadata: metadata,
-            readOnly: !!metadata.ui?.readOnly
-        });
-
-        this.applyCommonDirectives(this.control, metadata, modelName);
-
-        (this.control as GeolocationControl).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 geolocation object.
-     * @returns {unknown} The geolocation value.
-     */
-    protected getValue(): unknown {
-        return this.control ? (this.control as GeolocationControl).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 GeolocationPlugin.ts
+ * @description Renders a GeolocationControl component for capturing latitude/longitude coordinates.
+ */
+
+import { HardwareControlPlugin } from "./HardwareControlPlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import Control from "sap/ui/core/Control";
+import GeolocationControl from "../../controls/GeolocationControl";
+import { PropertyBindingInfo } from "sap/ui/base/ManagedObject";
+import { isRecord } from "../../utils/TypeGuards";
+import { I18n, TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Plugin responsible for rendering the hardware `GeolocationControl` widget.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export class GeolocationPlugin extends HardwareControlPlugin<GeolocationControl> {
+    protected readonly HardwareControlClass = GeolocationControl;
+
+    /**
+     * Renders formatted coordinate text (`Lat: x, Lng: y`) 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 Text control.
+     */
+    protected renderDisplayControl(
+        _metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string,
+        engineScopeId?: string
+    ): Control {
+        const geoBinding = this.generateBindingInfo(bindingPath, modelName, undefined, {
+            formatter: (val: unknown) => {
+                if (isRecord(val) && val.lat !== undefined && val.lng !== undefined) {
+                    return I18n.getText(TEXT_KEY.geolocationCoordinates, [String(val.lat), String(val.lng)]);
+                }
+                if (typeof val === "string") {
+                    return val;
+                }
+                return "";
+            }
+        }) as PropertyBindingInfo;
+        return this.createDisplayText(engineScopeId, bindingPath, geoBinding);
+    }
+}

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

@@ -0,0 +1,154 @@
+/**
+ * @file HardwareControlPlugin.ts
+ * @description Shared abstract base class for hardware/media control plugins (Signature, Camera, VoiceInput, Geolocation, RichText).
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import BaseHardwareControl, { $BaseHardwareControlSettings } from "../../controls/BaseHardwareControl";
+import Control from "sap/ui/core/Control";
+import Event from "sap/ui/base/Event";
+import ImageControl from "sap/m/Image";
+import { AccessibilityUtil } from "../../utils/AccessibilityUtil";
+import { UrlValidator } from "../../utils/UrlValidator";
+
+/**
+ * Shared abstract base class for plugins wrapping a `BaseHardwareControl` subclass.
+ * Consolidates edit-mode hardware control instantiation, `capture` event notification,
+ * `getValue`, `applyState`, and safe image display-mode rendering.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export abstract class HardwareControlPlugin<T extends BaseHardwareControl = BaseHardwareControl> extends BasePlugin {
+    protected abstract readonly HardwareControlClass: new (settings?: $BaseHardwareControlSettings) => T;
+
+    /**
+     * Renders the display-mode control when `this.isEditable === false`.
+     *
+     * @param metadata The property metadata.
+     * @param bindingPath The property binding path.
+     * @param modelName The UI5 JSONModel name.
+     * @param engineScopeId The deterministic scope ID.
+     * @returns {Control} The display-mode UI5 control.
+     */
+    protected abstract renderDisplayControl(
+        metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string,
+        engineScopeId?: string
+    ): Control;
+
+    /**
+     * Helper for `SignaturePlugin` and `CameraPlugin` to render a URL-validated `sap.m.Image` in display mode.
+     *
+     * @param metadata The property metadata.
+     * @param bindingPath The property binding path.
+     * @param modelName The UI5 JSONModel name.
+     * @param engineScopeId The deterministic scope ID.
+     * @param defaultAlt Fallback alt text when `metadata.ui.label` is omitted.
+     * @returns {Control} The configured `sap.m.Image` control.
+     */
+    protected renderSafeImageDisplay(
+        metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string,
+        engineScopeId: string | undefined,
+        defaultAlt: string
+    ): Control {
+        const safeSrc = this.generateBindingInfo(bindingPath, modelName, undefined, {
+            formatter: (val: unknown) => (UrlValidator.isSafeImageSource(val) ? val.trim() : "")
+        });
+        this.control = new ImageControl({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            src: safeSrc as unknown as string,
+            width: "400px",
+            height: "150px",
+            alt: metadata.ui?.label || defaultAlt
+        });
+        this.applyCommonDirectives(this.control, metadata, modelName);
+        return this.control;
+    }
+
+    /**
+     * Renders the `BaseHardwareControl` component in edit mode or delegates to `renderDisplayControl` in display mode.
+     *
+     * @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 hardware or display control.
+     */
+    public render(
+        metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string = "meta",
+        engineScopeId?: string,
+        onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void
+    ): Control {
+        this.initialize(metadata, bindingPath, modelName, onChange);
+
+        if (!this.isEditable) {
+            return this.renderDisplayControl(metadata, bindingPath, modelName, engineScopeId);
+        }
+
+        const HwClass = this.HardwareControlClass;
+        const hwControl = new HwClass({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            value: this.generateBindingInfo(bindingPath, modelName),
+            schemaMetadata: metadata,
+            readOnly: !this.isControlEditable()
+        });
+
+        this.control = hwControl;
+        this.applyCommonDirectives(this.control, metadata, modelName);
+
+        hwControl.attachEvent("capture", (oEvent: Event) => {
+            this.notifyChange((oEvent.getSource() as Control).getId());
+        });
+
+        return this.control;
+    }
+
+    /**
+     * Names the text-entry control nested inside the hardware composite rather than the composite itself.
+     *
+     * `BaseHardwareControl` declares no `ariaLabelledBy` association, so a name written to the outer control
+     * is dropped on the floor while the element the user actually focuses — the transcription input of the
+     * voice widget, the coordinate input of the geolocation widget, the fallback editor of the rich-text
+     * widget — stays anonymous. Only `sap.m.InputBase` descendants are considered: the composites also hold
+     * capture and clear buttons whose own labels must not be overwritten by the field's name.
+     *
+     * @param control The outer hardware control produced by `render`.
+     * @returns {Control[]} The nested text-entry controls, or the composite itself when it has none.
+     */
+    protected override resolveAccessibleNameTargets(control: Control): Control[] {
+        const root = this.mainControl ?? control;
+        const nested = AccessibilityUtil.collectInputDescendants(root);
+        return nested.length > 0 ? nested : [root];
+    }
+
+    /**
+     * Retrieves the current `value` property from the `BaseHardwareControl` instance (or bound model in display mode).
+     *
+     * @param sourceControl Optional cloned control instance for table rows.
+     * @returns {unknown} The current hardware value.
+     */
+    protected getValue(sourceControl?: Control): unknown {
+        if (!this.isEditable) {
+            return this.getModelValue(sourceControl) ?? null;
+        }
+        const target = sourceControl || this.control;
+        return target ? target.getProperty("value") : null;
+    }
+
+    /**
+     * Applies dynamic `readOnly` state to the `BaseHardwareControl` instance.
+     */
+    protected applyState(): void {
+        if (this.control && this.metadata && this.isEditable) {
+            this.control.setProperty("readOnly", !this.isControlEditable());
+        }
+    }
+}

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

@@ -1,57 +1,81 @@
-import { BasePlugin } from "./BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import Link from "sap/m/Link";
-import Input from "sap/m/Input";
-import Control from "sap/ui/core/Control";
-
-export class LinkPlugin extends BasePlugin {
-    public render(fieldMetadata: IPropertyMetadata, bindingPath: string, modelName: string = "meta", engineScopeId?: string, onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void): Control {
-        this.onChange = onChange;
-        this.metadata = fieldMetadata;
-        this.fieldKey = bindingPath.replace("/", "");
-        
-        if (!this.isEditable) {
-            this.control = new Link({
-                id: this.generateStableId(engineScopeId, bindingPath),
-                text: this.generateBindingInfo(bindingPath, modelName),
-                href: this.generateBindingInfo(bindingPath, modelName),
-                target: "_blank"
-            });
-            this.applyCommonDirectives(this.control, fieldMetadata, modelName);
-            return this.control as Control;
-        }
-
-        // Editable mode: user needs to type a URL, so we use an Input configured for URLs
-        this.control = new Input({
-            id: this.generateStableId(engineScopeId, bindingPath),
-            value: this.generateBindingInfo(bindingPath, modelName),
-            type: "Url",
-            maxLength: fieldMetadata.maxLength || 0,
-            required: !!fieldMetadata.required,
-            change: (oEvent: sap.ui.base.Event) => {
-                const result = this.validate();
-                if (this.onChange) this.onChange(result.isValid, this.fieldKey, result.errorMessage);
-            }
-        });
-        
-        this.applyCommonDirectives(this.control, fieldMetadata, modelName);
-        return this.control as Control;
-    }
-    
-    protected getValue(): unknown {
-        if (!this.control) return null;
-        if (this.control.getMetadata().getName() === "sap.m.Input") {
-            return (this.control as Input).getProperty('value');
-        }
-        return (this.control as Link).getHref();
-    }
-    
-    protected applyState(): void {
-        if (!this.control || !this.metadata) return;
-        if (this.control.getMetadata().getName() === "sap.m.Input") {
-            const input = this.control as Input;
-            input.setEditable(!this.metadata.ui?.readOnly);
-            input.setRequired(!!this.metadata.required);
-        }
-    }
-}
+/**
+ * @file LinkPlugin.ts
+ * @description Renders a sap.m.Link control for URI/URL strings with safe protocol validation.
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import Link from "sap/m/Link";
+import Control from "sap/ui/core/Control";
+import { UrlValidator } from "../../utils/UrlValidator";
+
+/**
+ * Handles rendering logic for URI/URL strings as clickable links (`sap.m.Link`).
+ * Validates the target URL protocol via `UrlValidator.isSafeNavigationUrl` to block unsafe schemes (`javascript:`, `data:`).
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export class LinkPlugin extends BasePlugin {
+    protected override readonly isNavigationAffordance: boolean = true;
+
+    /**
+     * Renders a `sap.m.Link` component bound to the target URL string.
+     *
+     * @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 Link control.
+     */
+    public render(
+        metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string = "meta",
+        engineScopeId?: string,
+        onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void
+    ): Control {
+        this.initialize(metadata, bindingPath, modelName, onChange);
+
+        const safeHrefBinding = this.generateBindingInfo(bindingPath, modelName, undefined, {
+            formatter: (val: unknown) => (UrlValidator.isSafeNavigationUrl(val) ? val.trim() : "")
+        });
+
+        this.control = new Link({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            text: (metadata.ui?.placeholder || this.generateBindingInfo(bindingPath, modelName)) as unknown as string,
+            href: safeHrefBinding as unknown as string,
+            target: "_blank",
+            enabled: this.isAffordanceEnabled()
+        });
+
+        this.applyCommonDirectives(this.control, metadata, modelName);
+        return this.control;
+    }
+
+    /**
+     * Retrieves the current URL value from the bound model or Link `href` property.
+     * @param sourceControl Optional cloned control instance for table rows.
+     * @returns {unknown} The URL string.
+     */
+    protected getValue(sourceControl?: Control): unknown {
+        const target = sourceControl || this.control;
+        const modelVal = this.getModelValue(target);
+        if (modelVal !== undefined && modelVal !== null) {
+            return modelVal;
+        }
+        return target ? (target as Link).getProperty("href") : null;
+    }
+
+    /**
+     * Applies dynamic enabled state. A hyperlink stays followable in display mode and under `ui.readOnly`;
+     * only an explicit `ui.enabled: false` switches it off.
+     */
+    protected applyState(): void {
+        if (this.control && this.metadata && !this.metadata.ui?.enabledOn) {
+            const link = this.control as Link;
+            link.setEnabled(this.isAffordanceEnabled());
+        }
+    }
+}

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

@@ -1,59 +1,101 @@
-/**
- * @file MessageStripPlugin.ts
- * @description Renders a sap.m.MessageStrip for informational text.
- */
-
-import { BasePlugin } from "./BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import MessageStrip from "sap/m/MessageStrip";
-import Control from "sap/ui/core/Control";
-
-/**
- * Renders read-only informational alerts within the layout.
- * Does not emit values to the payload.
- * 
- * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
- * @public
- */
-export class MessageStripPlugin extends BasePlugin {
-    /**
-     * Renders a `sap.m.MessageStrip` component.
-     * 
-     * @param fieldMetadata 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 MessageStrip control.
-     */
-    public render(fieldMetadata: IPropertyMetadata,  bindingPath: string,  modelName: string = "meta", engineScopeId?: string, onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void): Control {
-        this.onChange = onChange;
-        this.metadata = fieldMetadata;
-        this.fieldKey = bindingPath.startsWith('/') ? bindingPath.substring(1) : bindingPath;
-        
-        // Use binding to display text if the field has a value, otherwise use the label
-        this.control = new MessageStrip({
-            id: this.generateStableId(engineScopeId, bindingPath),
-            text: this.generateBindingInfo(bindingPath, modelName),
-            type: "Information", // Can be driven by schema arguments in the future
-            showIcon: true,
-            showCloseButton: false
-        });
-
-        return this.control as Control;
-    }
-
-    /**
-     * Read-only control, returns null.
-     */
-    protected getValue(): unknown {
-        return null; // Read-only component
-    }
-
-    /**
-     * Read-only control, no dynamic state needed.
-     */
-    protected applyState(): void {
-        // Read-only component, no dynamic state needed currently
-    }
-}
+/**
+ * @file MessageStripPlugin.ts
+ * @description Renders a sap.m.MessageStrip for inline contextual notifications and banners.
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import MessageStrip from "sap/m/MessageStrip";
+import Control from "sap/ui/core/Control";
+import { MessageType } from "sap/ui/core/library";
+
+/**
+ * Maps a schema `ui.valueState` string to a UI5 `MessageType` enum value.
+ * @param valueState The schema valueState string (`"Information"`, `"Warning"`, `"Error"`, `"Success"`).
+ * @returns {MessageType} The resolved `sap.ui.core.MessageType`.
+ */
+function resolveMessageType(valueState?: string): MessageType {
+    switch (valueState) {
+        case "Warning":
+            return MessageType.Warning;
+        case "Error":
+            return MessageType.Error;
+        case "Success":
+            return MessageType.Success;
+        case "Information":
+        default:
+            return MessageType.Information;
+    }
+}
+
+/**
+ * Plugin responsible for rendering non-editable inline banners (`sap.m.MessageStrip`).
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export class MessageStripPlugin extends BasePlugin {
+    /**
+     * Renders a `sap.m.MessageStrip` bound to the property text.
+     *
+     * @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 MessageStrip control.
+     */
+    public render(
+        metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string = "meta",
+        engineScopeId?: string,
+        onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void
+    ): Control {
+        this.initialize(metadata, bindingPath, modelName, onChange);
+
+        const strip = new MessageStrip({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            text: this.generateBindingInfo(bindingPath, modelName) as unknown as string,
+            type: resolveMessageType(metadata.ui?.valueState),
+            showIcon: true,
+            showCloseButton: false
+        });
+
+        strip.addStyleClass("sapUiTinyMarginBottom");
+
+        this.control = strip;
+        this.applyCommonDirectives(this.control, metadata, modelName);
+
+        return this.control;
+    }
+
+    /**
+     * `MessageStrip` is a read-only display widget and never blocks form submission.
+     * @returns {{ isValid: boolean; errorMessage?: string }} Always `{ isValid: true }`.
+     */
+    public override validate(): { isValid: boolean; errorMessage?: string } {
+        return { isValid: true };
+    }
+
+    /**
+     * Retrieves the current banner text from the `MessageStrip`.
+     * @returns {unknown} The text string.
+     */
+    protected getValue(): unknown {
+        return this.control ? (this.control as MessageStrip).getText() : "";
+    }
+
+    /**
+     * Applies dynamic `valueState` updates to the `MessageStrip` type.
+     */
+    protected applyState(): void {
+        if (!this.control || !this.metadata) {
+            return;
+        }
+        const strip = this.control as MessageStrip;
+        if (this.metadata.ui?.valueState) {
+            strip.setType(resolveMessageType(this.metadata.ui.valueState));
+        }
+    }
+}