@siliconst/metaui 1.4.44 → 2.0.0

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

@@ -1,75 +1,46 @@
-import { BasePlugin } from "../controls/BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import Control from "sap/ui/core/Control";
-import VoiceInputControl from "../../controls/VoiceInputControl";
-import TextControl from "sap/m/Text";
-
-export class VoiceInputPlugin extends BasePlugin {
-    /**
-     * Renders a `VoiceInputControl` 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 VoiceInputControl.
-     */
-    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: unknown) => {
-                        if (!val || val === "undefined" || val === "null") return "";
-                        return val;
-                    }
-                })
-            }) as Control;
-            this.applyCommonDirectives(this.control, metadata, modelName);
-            return this.control as Control;
-        }
-
-        this.control = new VoiceInputControl({
-            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 VoiceInputControl).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 voice transcription text.
-     * @returns {unknown} The text string.
-     */
-    protected getValue(): unknown {
-        return this.control ? (this.control as VoiceInputControl).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 VoiceInputPlugin.ts
+ * @description Renders a VoiceInputControl component for speech-to-text transcription.
+ */
+
+import { HardwareControlPlugin } from "./HardwareControlPlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import Control from "sap/ui/core/Control";
+import VoiceInputControl from "../../controls/VoiceInputControl";
+import { PropertyBindingInfo } from "sap/ui/base/ManagedObject";
+
+/**
+ * Plugin responsible for rendering the hardware `VoiceInputControl` speech-to-text widget.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export class VoiceInputPlugin extends HardwareControlPlugin<VoiceInputControl> {
+    protected readonly HardwareControlClass = VoiceInputControl;
+
+    /**
+     * Renders a `sap.m.Text` control in display mode, sanitizing empty/null strings.
+     *
+     * @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 voiceBinding = this.generateBindingInfo(bindingPath, modelName, undefined, {
+            formatter: (val: unknown) => {
+                if (!val || val === "undefined" || val === "null") {
+                    return "";
+                }
+                return String(val);
+            }
+        }) as PropertyBindingInfo;
+        return this.createDisplayText(engineScopeId, bindingPath, voiceBinding);
+    }
+}

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

@@ -1,111 +1,175 @@
-/**
- * @file LiveSearchPlugin.ts
- * @description A custom datasource plugin that provides asynchronous live search (autocomplete) functionality.
- */
-
-import { BasePlugin } from "../controls/BasePlugin";
-import Event from "sap/ui/base/Event";
-
-import { IPropertyMetadata, IRemoteValueHelpConfig } from "../../interfaces/ISchema";
-import Input from "sap/m/Input";
-import Item from "sap/ui/core/Item";
-import Control from "sap/ui/core/Control";
-import { Logger } from "../../utils/Logger";
-
-/**
- * A custom datasource plugin that provides asynchronous live search (autocomplete) functionality.
- * As the user types, it fetches suggestions from a remote endpoint.
- * 
- * @namespace nz.co.siliconst.ui5.metaui.plugins.datasources
- * @public
- */
-export class LiveSearchPlugin extends BasePlugin {
-    public render(fieldMetadata: IPropertyMetadata, bindingPath: string, modelName: string = "meta"): Control {
-        this.metadata = fieldMetadata;
-        
-        const input = new Input({
-            value: `{${modelName}>${bindingPath}}`,
-            enabled: !fieldMetadata.ui?.readOnly,
-            placeholder: "Type to search...",
-            showSuggestion: true,
-            suggest: (oEvent: Event) => {
-                const query = (oEvent as Event).getParameter("suggestValue");
-                this.fetchSuggestions(input, query);
-            },
-            change: (oEvent: Event) => {
-                this.validate();
-            }
-        });
-
-        this.control = input;
-        return this.control as Control;
-    }
-
-    /**
-     * Executes the REST fetch for suggestions based on a query. Can be overridden by mock subclasses.
-     * @param input The UI5 Input to populate with suggestions.
-     * @param query The text typed by the user.
-     */
-    protected fetchSuggestions(input: Input, query: string): void {
-        const vhConfig = this.metadata?.valueHelp as IRemoteValueHelpConfig;
-        if (!vhConfig || !vhConfig.url) {
-            Logger.error("LiveSearchPlugin requires a valid valueHelp configuration with a URL.", "", "LiveSearchPlugin");
-            return;
-        }
-
-        if (!query) {
-            input.removeAllSuggestionItems();
-            return;
-        }
-        
-        input.setBusy(true);
-        
-        // In a real application, the query parameter would be passed to the backend (e.g. ?q=query)
-        // Here, we simulate fetching and filter locally, but subclasses can override this entirely.
-        fetch(vhConfig.url)
-            .then(res => res.json())
-            .then((data: Record<string, unknown>[]) => {
-                const keyPath = vhConfig.keyPath || "key";
-                const textPath = vhConfig.textPath || "text";
-                
-                input.removeAllSuggestionItems();
-
-                // Simple client-side filter for demonstration
-                const lowerQuery = query.toLowerCase();
-                const filteredData = data.filter(item => {
-                    const textValue = String(item[textPath] || item[keyPath]).toLowerCase();
-                    return textValue.includes(lowerQuery);
-                });
-                
-                filteredData.forEach(itemData => {
-                    input.addSuggestionItem(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, "LiveSearchPlugin");
-            })
-            .finally(() => {
-                input.setBusy(false);
-            });
-    }
-
-    /**
-     * Retrieves the current input value.
-     * @returns {unknown} The input text.
-     */
-    protected getValue(): unknown {
-        return this.control ? (this.control as Input).getValue() : null;
-    }
-
-    /**
-     * Applies dynamic read-only state.
-     */
-    protected applyState(): void {
-        if (this.control && this.metadata) {
-            (this.control as Input).setEnabled(!this.metadata.ui?.readOnly);
-        }
-    }
-}
+/**
+ * @file LiveSearchPlugin.ts
+ * @description Renders a sap.m.Input with live type-ahead suggestions fetched from a remote REST endpoint.
+ */
+
+import { TextLikeInputPlugin } from "../controls/TextLikeInputPlugin";
+import { IDataSourceConfig, IPropertyMetadata } from "../../interfaces/ISchema";
+import { ControlDirectiveUtil, extractDataSourceList } from "../../utils/ControlDirectiveUtil";
+import Input from "sap/m/Input";
+import SuggestionItem from "sap/m/SuggestionItem";
+import Control from "sap/ui/core/Control";
+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` control with remote live type-ahead suggestions (`ui.widget = "liveSearch"`).
+ * Includes debounce throttling and monotonic request sequencing to discard out-of-order network responses.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.datasources
+ * @internal
+ */
+export class LiveSearchPlugin extends TextLikeInputPlugin {
+    private debounceTimer?: ReturnType<typeof setTimeout>;
+    private requestSequence: number = 0;
+
+    /**
+     * Constructs a `sap.m.Input` configured with `showSuggestion: true` and remote suggestion fetching.
+     *
+     * @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 {
+        const ds = ControlDirectiveUtil.resolveDataSourceConfig(metadata);
+        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.dataSourceSearchPlaceholder),
+            required: this.isRequired(),
+            showSuggestion: true,
+            startSuggestion: 2,
+            filterSuggests: false,
+            suggest: (oEvent: Event) => {
+                const src = oEvent.getSource() as Input;
+                const params = oEvent.getParameters() as { suggestValue?: string };
+                const term = params.suggestValue || "";
+                this.scheduleSearch(src, term, ds);
+            },
+            suggestionItemSelected: (oEvent: Event) => {
+                const src = oEvent.getSource() as Input;
+                const params = oEvent.getParameters() as { selectedItem?: SuggestionItem };
+                const selectedItem = params.selectedItem;
+                if (selectedItem) {
+                    const selectedVal = selectedItem.getKey() || selectedItem.getText();
+                    src.setValue(selectedVal);
+                    this.commitValue(src, selectedVal);
+                }
+                this.notifyChange(src.getId());
+            },
+            change: (oEvent: Event) => {
+                const src = oEvent.getSource() as Input;
+                this.notifyChange(src.getId());
+            }
+        });
+    }
+
+    /**
+     * Schedules a debounced remote search query (250ms) and cancels any pending timer.
+     *
+     * @param input The target `sap.m.Input` control.
+     * @param term The user's search term.
+     * @param ds The configured `IDataSourceConfig` block.
+     */
+    protected scheduleSearch(input: Input, term: string, ds?: IDataSourceConfig): void {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        if (!ds || !ds.url || term.trim().length < 2) {
+            return;
+        }
+        if (!UrlValidator.isSafeDataSourceUrl(ds.url)) {
+            Logger.warn(
+                `REFUSED dataSource.url '${ds.url}': blocked by the data source URL policy, no search term was sent.`,
+                undefined,
+                "LiveSearchPlugin"
+            );
+            return;
+        }
+        const currentSeq = ++this.requestSequence;
+        this.debounceTimer = setTimeout(() => {
+            void this.executeSearch(input, term.trim(), ds.url, ds.keyField, ds.textField, ds.dataPath, currentSeq);
+        }, 250);
+    }
+
+    /**
+     * Executes the remote HTTP request and populates `SuggestionItem` aggregations if the sequence is still current.
+     *
+     * @param input The target `sap.m.Input` control.
+     * @param term The search query string.
+     * @param urlTemplate The endpoint URL or template containing `{query}`.
+     * @param keyField The JSON property key for item keys.
+     * @param textField The JSON property key for item display text.
+     * @param dataPath Optional dot-separated path to the array inside the response payload.
+     * @param seq The monotonic request sequence number.
+     */
+    private async executeSearch(
+        input: Input,
+        term: string,
+        urlTemplate: string,
+        keyField: string,
+        textField: string,
+        dataPath: string | undefined,
+        seq: number
+    ): Promise<void> {
+        try {
+            const targetUrl = urlTemplate.includes("{query}")
+                ? urlTemplate.replace("{query}", encodeURIComponent(term))
+                : `${urlTemplate}${urlTemplate.includes("?") ? "&" : "?"}q=${encodeURIComponent(term)}`;
+
+            if (!UrlValidator.isSafeDataSourceUrl(targetUrl)) {
+                throw new Error("target URL blocked by the data source URL policy");
+            }
+
+            const response = await fetch(targetUrl);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+
+            const rawPayload: unknown = await response.json();
+            if (seq !== this.requestSequence || input.isDestroyed()) {
+                return;
+            }
+
+            const items = extractDataSourceList(rawPayload, dataPath);
+            input.destroySuggestionItems();
+
+            for (const row of items) {
+                if (isRecord(row)) {
+                    const keyVal = row[keyField] !== undefined ? String(row[keyField]) : "";
+                    const textVal = row[textField] !== undefined ? String(row[textField]) : keyVal;
+                    input.addSuggestionItem(
+                        new SuggestionItem({
+                            key: keyVal,
+                            text: textVal,
+                            description: keyVal !== textVal ? keyVal : ""
+                        })
+                    );
+                }
+            }
+        } catch (err) {
+            Logger.warn(`Live search request failed: ${(err as Error).message}`, undefined, "LiveSearchPlugin");
+        }
+    }
+
+    /**
+     * Clears any pending debounce timer and destroys the underlying UI5 control.
+     */
+    public override destroy(): void {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = undefined;
+        }
+        super.destroy();
+    }
+}

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

@@ -1,67 +1,148 @@
-/**
- * @file ODataListBindingPlugin.ts
- * @description A custom datasource plugin that binds a ComboBox to an OData EntitySet.
- */
-
-import { BasePlugin } from "../controls/BasePlugin";
-import Event from "sap/ui/base/Event";
-
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import ComboBox from "sap/m/ComboBox";
-import Item from "sap/ui/core/Item";
-import Control from "sap/ui/core/Control";
-
-/**
- * Renders a ComboBox natively bound to an OData Model entity set.
- * Expects args: { path: "/Categories", key: "ID", text: "Name" }
- * 
- * @namespace nz.co.siliconst.ui5.metaui.plugins.datasources
- * @public
- */
-export class ODataListBindingPlugin extends BasePlugin {
-    public render(fieldMetadata: IPropertyMetadata, bindingPath: string, modelName: string = "meta"): Control {
-        this.metadata = fieldMetadata;
-        
-        const args = (fieldMetadata.ui?.args as Record<string, string>) || { path: "/", key: "ID", text: "Name" };
-        
-        this.control = new ComboBox({
-            selectedKey: `{${modelName}>${bindingPath}}`,
-            enabled: !fieldMetadata.ui?.readOnly,
-            placeholder: fieldMetadata.ui?.label || "Select...",
-            change: (oEvent: Event) => {
-                const selectedItem = (oEvent.getParameter("selectedItem") as unknown) as Item;
-                const val = selectedItem?.getKey();
-                this.validate();
-            }
-        });
-
-        // Natively bind aggregation to the default model (OData)
-        (this.control as ComboBox).bindAggregation("items", {
-            path: args.path,
-            template: new Item({
-                key: `{${args.key}}`,
-                text: `{${args.text}}`
-            }),
-            templateShareable: false
-        });
-
-        return this.control as Control;
-    }
-
-    /**
-     * 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 ODataListBindingPlugin.ts
+ * @description Renders a sap.m.ComboBox bound directly to an OData entity set path.
+ */
+
+import { BasePlugin } from "../controls/BasePlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import ComboBox from "sap/m/ComboBox";
+import Item from "sap/ui/core/Item";
+import Control from "sap/ui/core/Control";
+import JSONModel from "sap/ui/model/json/JSONModel";
+import Event from "sap/ui/base/Event";
+import { Logger } from "../../utils/Logger";
+import { I18n, TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Plugin responsible for rendering a `sap.m.ComboBox` bound to a live OData entity set (`ui.widget = "odataSelect"`).
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.datasources
+ * @internal
+ */
+export class ODataListBindingPlugin extends BasePlugin {
+    /**
+     * Checks that `dataSource.url` is an OData model entity set path rather than an absolute or
+     * protocol-relative URL, so a schema cannot redirect the aggregation binding off the configured service.
+     *
+     * @param rawPath The configured `dataSource.url`.
+     * @returns {boolean} True when the value is a plain model path.
+     */
+    private static isEntitySetPath(rawPath: string): boolean {
+        const trimmed = rawPath.trim();
+        return Boolean(trimmed) && !trimmed.startsWith("//") && !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(trimmed);
+    }
+
+    /**
+     * Renders a `sap.m.ComboBox` whose `items` aggregation is bound to the configured OData entity set.
+     *
+     * @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 ComboBox or Text 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.createDisplayText(engineScopeId, bindingPath);
+        }
+
+        const ds = metadata.ui?.dataSource;
+        const bindingInfo = this.generateBindingInfo(bindingPath, modelName) as unknown as string;
+        const combo = new ComboBox({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            selectedKey: bindingInfo,
+            value: !ds?.url ? bindingInfo : undefined,
+            placeholder: metadata.ui?.placeholder || I18n.getText(TEXT_KEY.dataSourceSelectPlaceholder),
+            width: "100%",
+            required: this.isRequired(),
+            change: (oEvent: Event) => {
+                const src = oEvent.getSource() as ComboBox;
+                const nextVal = src.getSelectedKey() || src.getValue();
+                const model = (src.getModel(modelName) || this.engineContext?.getModel()) as JSONModel | undefined;
+                if (model) {
+                    model.setProperty(this.resolveAbsolutePath(src), nextVal);
+                }
+                this.notifyChange(src.getId());
+            }
+        });
+
+        if (!ds || !ds.url || !ds.keyField || !ds.textField) {
+            Logger.warn("Incomplete dataSource configuration for odataSelect widget.", undefined, "ODataListBindingPlugin");
+        } else if (!ODataListBindingPlugin.isEntitySetPath(ds.url)) {
+            Logger.warn(
+                `REFUSED dataSource.url '${ds.url}': odataSelect expects a model entity set path, not an absolute URL.`,
+                undefined,
+                "ODataListBindingPlugin"
+            );
+        } else {
+            const odataModelPrefix = ds.modelName ? `${ds.modelName}>` : "";
+            combo.bindAggregation("items", {
+                path: `${odataModelPrefix}${ds.url}`,
+                template: new Item({
+                    key: `{${odataModelPrefix}${ds.keyField}}`,
+                    text: `{${odataModelPrefix}${ds.textField}}`
+                }),
+                templateShareable: true
+            });
+        }
+
+        combo.attachModelContextChange((oEvent: Event) => {
+            const src = (oEvent.getSource() as ComboBox) || combo;
+            if (src.isDestroyed()) return;
+            const boundVal = this.getModelValue(src);
+            if (boundVal !== undefined && boundVal !== null && boundVal !== "") {
+                const strVal = String(boundVal);
+                if (!src.getItems().some((it) => it.getKey() === strVal)) {
+                    src.addItem(new Item({ key: strVal, text: strVal }));
+                }
+            }
+        });
+
+        this.control = combo;
+        this.applyCommonDirectives(this.control, metadata, modelName);
+
+        return this.control;
+    }
+
+    /**
+     * Retrieves the currently selected key or typed value from the `ComboBox`.
+     *
+     * @param sourceControl Optional cloned row control to read from when bound inside a `TableLayout`.
+     * @returns {unknown} The selected key string.
+     */
+    protected getValue(sourceControl?: Control): unknown {
+        if (!this.isEditable) {
+            return this.getModelValue(sourceControl) ?? "";
+        }
+        const target = (sourceControl || this.control) as ComboBox | undefined;
+        if (!target || typeof target.getSelectedKey !== "function") {
+            return this.getModelValue(target) ?? "";
+        }
+        const liveVal = target.getSelectedKey() || target.getValue();
+        if (liveVal === "" && (!target.getDomRef() || target.getItems().length === 0)) {
+            return this.getModelValue(target) ?? "";
+        }
+        return liveVal;
+    }
+
+    /**
+     * Applies dynamic `readOnly` and `required` state updates to the `ComboBox`.
+     */
+    protected applyState(): void {
+        if (!this.control || !this.metadata || !this.isEditable) {
+            return;
+        }
+        const combo = this.control as ComboBox;
+        combo.setEditable(this.isControlEditable());
+        combo.setRequired(this.isRequired());
+    }
+}