@siliconst/metaui 1.4.44 → 2.0.0

package/src/nz/co/siliconst/ui5/metaui/plugins/datasources/RemoteValueHelpPlugin.ts

@@ -1,107 +1,183 @@
-/**
- * @file RemoteValueHelpPlugin.ts
- * @description A custom datasource plugin that simulates fetching data from a remote server.
- */
-
-import { BasePlugin } from "../controls/BasePlugin";
-import Event from "sap/ui/base/Event";
-
-import { IPropertyMetadata, IRemoteValueHelpConfig } from "../../interfaces/ISchema";
-import ComboBox from "sap/m/ComboBox";
-import Item from "sap/ui/core/Item";
-import Control from "sap/ui/core/Control";
-import { Logger } from "../../utils/Logger";
-
-/**
- * A custom datasource plugin that simulates fetching data from a remote server.
- * Proves out custom data sources that dynamically load value help.
- * 
- * @namespace nz.co.siliconst.ui5.metaui.plugins.datasources
- * @public
- */
-export class RemoteValueHelpPlugin extends BasePlugin {
-    private isLoaded = false;
-
-    /**
-     * Renders a `ComboBox` that simulates fetching data from a remote server.
-     * 
-     * @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.
-     * @returns {Control} The configured ComboBox control.
-     */
-    public render(fieldMetadata: IPropertyMetadata, bindingPath: string, modelName: string = "meta"): Control {
-        this.metadata = fieldMetadata;
-        
-        const comboBox = new ComboBox({
-            selectedKey: `{${modelName}>${bindingPath}}`,
-            enabled: !fieldMetadata.ui?.readOnly,
-            placeholder: "Select a country...",
-            change: (oEvent: Event) => {
-                const item = (oEvent as Event).getParameter("selectedItem");
-                const val = item ? item.getKey() : (oEvent as Event).getParameter("value"); // Allow free text as well
-                this.validate();
-            }
-        });
-
-        // Perform an async load against the REST endpoint
-        comboBox.attachEventOnce("loadItems", () => {
-            this.fetchData(comboBox);
-        });
-
-        this.control = comboBox;
-        return this.control as Control;
-    }
-
-    /**
-     * Executes the REST fetch for data.
-     * @param comboBox The UI5 ComboBox to populate.
-     */
-    protected fetchData(comboBox: ComboBox): void {
-        const vhConfig = this.metadata?.valueHelp as IRemoteValueHelpConfig;
-        if (!vhConfig || !vhConfig.url) {
-            Logger.error("RemoteValueHelpPlugin requires a valid valueHelp configuration with a URL.", "", "RemoteValueHelpPlugin");
-            return;
-        }
-        
-        comboBox.setBusy(true);
-        
-        fetch(vhConfig.url)
-            .then(res => res.json())
-            .then((data: Record<string, unknown>[]) => {
-                const keyPath = vhConfig.keyPath || "key";
-                const textPath = vhConfig.textPath || "text";
-                
-                data.forEach(itemData => {
-                    comboBox.addItem(new Item({ 
-                        key: String(itemData[keyPath]), 
-                        text: String(itemData[textPath] || itemData[keyPath])
-                    }));
-                });
-            })
-            .catch(err => {
-                Logger.error("Failed to load value help from " + vhConfig.url, err.message, "RemoteValueHelpPlugin");
-            })
-            .finally(() => {
-                comboBox.setBusy(false);
-                this.isLoaded = true;
-            });
-    }
-
-    /**
-     * Retrieves the current selected key.
-     * @returns {unknown} The selected key.
-     */
-    protected getValue(): unknown {
-        return this.control ? (this.control as ComboBox).getSelectedKey() : null;
-    }
-
-    /**
-     * Applies dynamic read-only state.
-     */
-    protected applyState(): void {
-        if (this.control && this.metadata) {
-            (this.control as ComboBox).setEnabled(!this.metadata.ui?.readOnly);
-        }
-    }
-}
+/**
+ * @file RemoteValueHelpPlugin.ts
+ * @description Renders a sap.m.Input with a ValueHelp icon that opens a sap.m.SelectDialog populated from a REST API.
+ */
+
+import { TextLikeInputPlugin } from "../controls/TextLikeInputPlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import { ControlDirectiveUtil, extractDataSourceList } from "../../utils/ControlDirectiveUtil";
+import Input from "sap/m/Input";
+import SelectDialog from "sap/m/SelectDialog";
+import StandardListItem from "sap/m/StandardListItem";
+import Control from "sap/ui/core/Control";
+import JSONModel from "sap/ui/model/json/JSONModel";
+import Filter from "sap/ui/model/Filter";
+import FilterOperator from "sap/ui/model/FilterOperator";
+import ListBinding from "sap/ui/model/ListBinding";
+import Event from "sap/ui/base/Event";
+import { Logger } from "../../utils/Logger";
+import { UrlValidator } from "../../utils/UrlValidator";
+import { isRecord } from "../../utils/TypeGuards";
+import { I18n, TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Plugin responsible for rendering an `Input` with a Value Help dialog (`sap.m.SelectDialog`)
+ * populated asynchronously from a REST endpoint (`ui.widget = "valueHelp"`).
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.datasources
+ * @internal
+ */
+export class RemoteValueHelpPlugin extends TextLikeInputPlugin {
+    private selectDialog?: SelectDialog;
+    private dialogModel?: JSONModel;
+    private activeTargetInput?: Input;
+
+    /**
+     * Constructs a `sap.m.Input` with `showValueHelp: true`.
+     *
+     * @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.
+     * @returns {Control} The configured Input control.
+     */
+    protected createEditableControl(
+        metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string,
+        engineScopeId?: string
+    ): Control {
+        return new Input({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            value: this.generateBindingInfo(bindingPath, modelName) as unknown as string,
+            placeholder: metadata.ui?.placeholder || I18n.getText(TEXT_KEY.dataSourceValueHelpPlaceholder),
+            required: this.isRequired(),
+            showValueHelp: true,
+            valueHelpRequest: (oEvent: Event) => {
+                const src = oEvent.getSource() as Input;
+                void this.openValueHelpDialog(src, metadata);
+            },
+            change: (oEvent: Event) => {
+                const src = oEvent.getSource() as Input;
+                this.notifyChange(src.getId());
+            }
+        });
+    }
+
+    /**
+     * Lazily creates and opens the `sap.m.SelectDialog`, fetching remote items from `metadata.ui.dataSource`.
+     *
+     * @param input The owning `sap.m.Input` control.
+     * @param metadata The property metadata containing `ui.dataSource`.
+     */
+    protected async openValueHelpDialog(input: Input, metadata: IPropertyMetadata): Promise<void> {
+        const ds = ControlDirectiveUtil.resolveDataSourceConfig(metadata);
+        if (!ds || !ds.url) {
+            Logger.warn("Missing dataSource.url for valueHelp widget.", undefined, "RemoteValueHelpPlugin");
+            return;
+        }
+        if (!UrlValidator.isSafeDataSourceUrl(ds.url)) {
+            Logger.warn(`REFUSED dataSource.url '${ds.url}': blocked by the data source URL policy.`, undefined, "RemoteValueHelpPlugin");
+            return;
+        }
+
+        this.activeTargetInput = input;
+
+        if (!this.selectDialog) {
+            this.dialogModel = new JSONModel({ items: [] });
+            const applyDialogFilter = (oEvent: Event): void => {
+                const params = oEvent.getParameters() as { value?: string; itemsBinding?: ListBinding };
+                const sValue = (params.value || "").trim();
+                const binding = params.itemsBinding;
+                if (binding) {
+                    if (!sValue) {
+                        binding.filter([]);
+                        return;
+                    }
+                    const combinedFilter = new Filter({
+                        filters: [
+                            new Filter(ds.textField, FilterOperator.Contains, sValue),
+                            new Filter(ds.keyField, FilterOperator.Contains, sValue)
+                        ],
+                        and: false
+                    });
+                    binding.filter([combinedFilter]);
+                }
+            };
+            this.selectDialog = new SelectDialog({
+                title: metadata.ui?.label || I18n.getText(TEXT_KEY.dataSourceValueHelpTitle),
+                liveChange: applyDialogFilter,
+                search: applyDialogFilter,
+                confirm: (oEvent: Event) => {
+                    const targetInput = this.activeTargetInput || (this.control as Input);
+                    const params = oEvent.getParameters() as { selectedItem?: StandardListItem };
+                    const selectedItem = params.selectedItem;
+                    if (selectedItem && targetInput) {
+                        const selectedKey = selectedItem.getDescription() || selectedItem.getTitle();
+                        targetInput.setValue(selectedKey);
+                        this.commitValue(targetInput, selectedKey);
+                        this.notifyChange(targetInput.getId());
+                    }
+                }
+            });
+
+            this.selectDialog.setModel(this.dialogModel, "vh");
+            this.selectDialog.bindAggregation("items", {
+                path: "vh>/items",
+                template: new StandardListItem({
+                    title: `{vh>${ds.textField}}`,
+                    description: `{vh>${ds.keyField}}`
+                })
+            });
+        }
+
+        try {
+            const response = await fetch(ds.url);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const rawData: unknown = await response.json();
+            if (!this.selectDialog || this.selectDialog.isDestroyed() || input.isDestroyed()) {
+                return;
+            }
+            const list = extractDataSourceList(rawData, ds.dataPath).map((entry) => {
+                if (!isRecord(entry)) {
+                    return entry;
+                }
+                const clone: Record<string, unknown> = { ...entry };
+                if (clone[ds.keyField] !== undefined && clone[ds.keyField] !== null) {
+                    clone[ds.keyField] = String(clone[ds.keyField]);
+                }
+                if (clone[ds.textField] !== undefined && clone[ds.textField] !== null) {
+                    clone[ds.textField] = String(clone[ds.textField]);
+                }
+                return clone;
+            });
+            this.dialogModel?.setProperty("/items", list);
+        } catch (err) {
+            Logger.error(`Failed to load ValueHelp data: ${(err as Error).message}`, undefined, "RemoteValueHelpPlugin");
+            if (!this.selectDialog || this.selectDialog.isDestroyed() || input.isDestroyed()) {
+                return;
+            }
+        }
+
+        const itemsBinding = this.selectDialog.getBinding("items") as ListBinding | undefined;
+        itemsBinding?.filter([]);
+        this.selectDialog.open("");
+    }
+
+    /**
+     * Destroys the cached `SelectDialog`, its `JSONModel`, and the primary `Input` control.
+     */
+    public override destroy(): void {
+        if (this.selectDialog) {
+            this.selectDialog.destroy();
+            this.selectDialog = undefined;
+        }
+        if (this.dialogModel) {
+            this.dialogModel.destroy();
+            this.dialogModel = undefined;
+        }
+        super.destroy();
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/formatters/CurrencyFormatterPlugin.ts

@@ -1,36 +1,106 @@
-/**
- * @file CurrencyFormatterPlugin.ts
- * @description Standard data formatter for currency values.
- */
-
-import { IFormatter } from "../../interfaces/IPipeline";
-import NumberFormat from "sap/ui/core/format/NumberFormat";
-
-/**
- * Standard data formatter for currency values.
- * Uses sap.ui.core.format.NumberFormat to format raw numbers into localized currency strings.
- * 
- * @namespace nz.co.siliconst.ui5.metaui.plugins.formatters
- * @public
- */
-export class CurrencyFormatterPlugin implements IFormatter {
-    private currencyFormat: NumberFormat;
-
-    constructor() {
-        this.currencyFormat = NumberFormat.getCurrencyInstance({
-            showMeasure: false
-        });
-    }
-
-    /**
-     * Formats raw JSON model data into a UI-friendly currency string.
-     * @param rawValue The raw numeric value from the JSON payload.
-     * @returns The formatted string for the UI control.
-     */
-    public format(rawValue: unknown, args?: unknown): string {
-        if (rawValue === null || rawValue === undefined) {
-            return "";
-        }
-        return "$" + this.currencyFormat.format(rawValue as number);
-    }
-}
+/**
+ * @file CurrencyFormatterPlugin.ts
+ * @description Standard data formatter for currency values.
+ */
+
+import { IFormatter, IParser } from "../../interfaces/IPipeline";
+import { safeToNumber, safeToString } from "../../core/SafeConvert";
+import NumberFormat from "sap/ui/core/format/NumberFormat";
+
+/**
+ * Reversible presentational formatter and parser for currency values.
+ * Uses `sap.ui.core.format.NumberFormat` to format raw numbers into localized currency strings
+ * and parse formatted currency strings back into JavaScript numbers.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.formatters
+ * @internal
+ */
+export class CurrencyFormatterPlugin implements IFormatter, IParser {
+    private currencyFormat: NumberFormat;
+
+    constructor() {
+        this.currencyFormat = NumberFormat.getCurrencyInstance({
+            showMeasure: false
+        });
+    }
+
+    /**
+     * Formats raw JSON model data into a UI-friendly currency string.
+     * @param rawValue The raw numeric value from the JSON payload.
+     * @param args Optional currency symbol prefix (defaults to `"$"`).
+     * @returns The formatted string for the UI control.
+     */
+    public format(rawValue: unknown, args?: unknown): string {
+        if (rawValue === null || rawValue === undefined || rawValue === "") {
+            return "";
+        }
+        if (typeof rawValue === "boolean") {
+            return safeToString(rawValue);
+        }
+        if (typeof rawValue === "string" && rawValue.trim() === "") {
+            return "";
+        }
+        const num = typeof rawValue === "number" ? rawValue : safeToNumber(rawValue);
+        if (!Number.isFinite(num)) {
+            return safeToString(rawValue);
+        }
+        const symbol = typeof args === "string" && args.trim().length > 0 ? args.trim() : "$";
+        if (num < 0) {
+            return "-" + symbol + this.currencyFormat.format(Math.abs(num));
+        }
+        return symbol + this.currencyFormat.format(num);
+    }
+
+    /**
+     * Parses a formatted currency display string back into a raw JavaScript `number`.
+     * Total function: returns the input unchanged when it cannot be interpreted as a finite number.
+     *
+     * @param uiValue The value extracted from the UI control.
+     * @param args Optional currency symbol prefix (defaults to `"$"`).
+     * @returns {unknown} The parsed numeric value, or the original input if unparseable.
+     */
+    public parse(uiValue: unknown, args?: unknown): unknown {
+        if (typeof uiValue === "number") {
+            return uiValue;
+        }
+        if (typeof uiValue !== "string") {
+            return uiValue;
+        }
+        const trimmed = uiValue.trim();
+        if (trimmed === "") {
+            return "";
+        }
+        const directNum = Number(trimmed);
+        if (Number.isFinite(directNum)) {
+            return directNum;
+        }
+        const symbol = typeof args === "string" && args.trim().length > 0 ? args.trim() : "$";
+        let candidate = trimmed;
+        let isNegative = false;
+        if (candidate.startsWith("-")) {
+            isNegative = true;
+            candidate = candidate.slice(1).trim();
+        } else if (candidate.startsWith("+")) {
+            candidate = candidate.slice(1).trim();
+        }
+        if (candidate.startsWith(symbol)) {
+            candidate = candidate.slice(symbol.length).trim();
+        }
+        if (!isNegative && candidate.startsWith("-")) {
+            isNegative = true;
+            candidate = candidate.slice(1).trim();
+        }
+        const normalized = candidate.replace(/,/g, "");
+        if (/^\d+(\.\d+)?$/.test(normalized)) {
+            const parsed = Number(normalized);
+            if (Number.isFinite(parsed)) {
+                return isNegative ? -parsed : parsed;
+            }
+        }
+        const ui5Parsed = this.currencyFormat.parse(candidate);
+        if (typeof ui5Parsed === "number" && Number.isFinite(ui5Parsed)) {
+            return isNegative ? -ui5Parsed : ui5Parsed;
+        }
+        return uiValue;
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/formatters/DateFormatterPlugin.ts

@@ -1,36 +1,113 @@
-/**
- * @file DateFormatterPlugin.ts
- * @description Standard data formatter for dates.
- */
-
-import { IFormatter } from "../../interfaces/IPipeline";
-import DateFormat from "sap/ui/core/format/DateFormat";
-
-/**
- * Formats ISO date strings to localized Medium formats (e.g., "Oct 15, 2026").
- * 
- * @namespace nz.co.siliconst.ui5.metaui.plugins.formatters
- * @public
- */
-export class DateFormatterPlugin implements IFormatter {
-    private dateFormat: DateFormat;
-
-    constructor() {
-        this.dateFormat = DateFormat.getDateInstance({ style: "medium" });
-    }
-
-    /**
-     * Formats raw JSON model data into a medium-style date string.
-     * @param rawValue The raw date string.
-     * @returns The formatted string for the UI control.
-     */
-    public format(rawValue: unknown, args?: unknown): string {
-        if (!rawValue) return "";
-        try {
-            const dateObj = new Date(rawValue as string);
-            return this.dateFormat.format(dateObj);
-        } catch (e) {
-            return rawValue as string; // Fallback to raw string if invalid date
-        }
-    }
-}
+/**
+ * @file DateFormatterPlugin.ts
+ * @description Standard data formatter for dates.
+ */
+
+import { IFormatter, IParser } from "../../interfaces/IPipeline";
+import { safeToString } from "../../core/SafeConvert";
+import DateFormat from "sap/ui/core/format/DateFormat";
+
+/**
+ * Reversible presentational formatter and parser for ISO dates (`"YYYY-MM-DD"` <-> localized medium format, e.g. `"Oct 15, 2026"`).
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.formatters
+ * @internal
+ */
+export class DateFormatterPlugin implements IFormatter, IParser {
+    private dateFormat: DateFormat;
+
+    constructor() {
+        this.dateFormat = DateFormat.getDateInstance({ style: "medium" });
+    }
+
+    /**
+     * Formats raw JSON model data into a medium-style date string.
+     * @param rawValue The raw date string.
+     * @param _args Optional unused formatter arguments.
+     * @returns The formatted string for the UI control.
+     */
+    public format(rawValue: unknown, _args?: unknown): string {
+        if (!rawValue) return "";
+        try {
+            if (rawValue instanceof Date) {
+                return Number.isNaN(rawValue.getTime()) ? "" : this.dateFormat.format(rawValue);
+            }
+            const strVal = safeToString(rawValue).trim();
+            const isoDateMatch = /^(\d{4})-(\d{2})-(\d{2})$/.exec(strVal);
+            if (isoDateMatch) {
+                const year = Number(isoDateMatch[1]);
+                const monthIdx = Number(isoDateMatch[2]) - 1;
+                const day = Number(isoDateMatch[3]);
+                const localDate = new Date(year, monthIdx, day);
+                if (
+                    Number.isNaN(localDate.getTime()) ||
+                    localDate.getFullYear() !== year ||
+                    localDate.getMonth() !== monthIdx ||
+                    localDate.getDate() !== day
+                ) {
+                    return strVal;
+                }
+                return this.dateFormat.format(localDate);
+            }
+            const dateObj = new Date(strVal);
+            if (Number.isNaN(dateObj.getTime())) {
+                return strVal;
+            }
+            return this.dateFormat.format(dateObj);
+        } catch (_e) {
+            // CATCH_EXEMPT: format() is a total function by contract. The unformatted raw value is
+            // itself the visible signal -- the user sees the date they supplied rather than a blank
+            // cell -- and this runs once per cell per render, so logging would be per-row noise.
+            return safeToString(rawValue);
+        }
+    }
+
+    /**
+     * Parses a medium-formatted date string (or ISO `YYYY-MM-DD` string) back into an ISO `YYYY-MM-DD` string.
+     * Total function: returns the input unchanged when it cannot be parsed as a valid date.
+     *
+     * @param uiValue The value extracted from the UI control.
+     * @param _args Optional unused parser arguments.
+     * @returns {unknown} The ISO `YYYY-MM-DD` string, or the original input if unparseable.
+     */
+    public parse(uiValue: unknown, _args?: unknown): unknown {
+        if (typeof uiValue !== "string") {
+            return uiValue;
+        }
+        const trimmed = uiValue.trim();
+        if (trimmed === "") {
+            return "";
+        }
+        const isoDateMatch = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
+        if (isoDateMatch) {
+            const year = Number(isoDateMatch[1]);
+            const monthIdx = Number(isoDateMatch[2]) - 1;
+            const day = Number(isoDateMatch[3]);
+            const localDate = new Date(year, monthIdx, day);
+            if (
+                !Number.isNaN(localDate.getTime()) &&
+                localDate.getFullYear() === year &&
+                localDate.getMonth() === monthIdx &&
+                localDate.getDate() === day
+            ) {
+                return trimmed;
+            }
+            return uiValue;
+        }
+        try {
+            const parsedDate = this.dateFormat.parse(trimmed) as Date | null;
+            if (parsedDate instanceof Date && !Number.isNaN(parsedDate.getTime())) {
+                const yyyy = String(parsedDate.getFullYear()).padStart(4, "0");
+                const mm = String(parsedDate.getMonth() + 1).padStart(2, "0");
+                const dd = String(parsedDate.getDate()).padStart(2, "0");
+                return `${yyyy}-${mm}-${dd}`;
+            }
+        } catch (err) {
+            // CATCH_EXEMPT: DateFormat.parse() throwing is how UI5 says 'this is not a date in the
+            // configured pattern', which is the answer parse() needs. The original input is returned
+            // unchanged below and remains visible and editable; nothing is discarded.
+            void err;
+        }
+        return uiValue;
+    }
+}