@siliconst/metaui 1.4.44 → 2.0.0

package/src/nz/co/siliconst/ui5/metaui/plugins/actions/ActionButtonPlugin.ts

@@ -0,0 +1,174 @@
+/**
+ * @file ActionButtonPlugin.ts
+ * @description Shared abstract base class for the action trigger plugins that render a single
+ * `sap.m.Button` carrying no user data: submit, clear, and URL navigation.
+ */
+
+import { BasePlugin } from "../controls/BasePlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import Button from "sap/m/Button";
+import Control from "sap/ui/core/Control";
+import Event from "sap/ui/base/Event";
+import { ButtonType } from "sap/m/library";
+import { PropertyBindingInfo } from "sap/ui/base/ManagedObject";
+import { I18n, MetaUITextKey } from "../../utils/I18n";
+
+/**
+ * Static configuration descriptor for a concrete `ActionButtonPlugin` subclass.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.actions
+ * @internal
+ */
+export interface IActionButtonConfig {
+    /** Bundle key for the label shown when the bound value supplies none. */
+    fallbackLabelKey: MetaUITextKey;
+    /** The `sap.m.ButtonType` applied to the trigger. */
+    buttonType: ButtonType;
+    /** The `sap-icon://` identifier shown on the trigger. */
+    icon: string;
+}
+
+/**
+ * Shared abstract base class for `SubmitFormActionPlugin`, `ClearFormActionPlugin`, and
+ * `UrlNavigationActionPlugin`.
+ *
+ * Action buttons hold no user data, so `getValue` is `null` and `validate` always passes. What the
+ * three otherwise repeat is the label binding, the button construction, and the `enabled` lifecycle.
+ * Collecting them here turns the one real difference between them into a declaration: the mutating
+ * buttons take the default and go dead under a read-only host, while a navigation affordance
+ * overrides {@link ActionButtonPlugin.resolveEnabled} and
+ * {@link ActionButtonPlugin.isEnabledStateExternallyOwned} and stays reachable.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.actions
+ * @internal
+ */
+export abstract class ActionButtonPlugin extends BasePlugin {
+    protected abstract readonly actionConfig: IActionButtonConfig;
+
+    /**
+     * Renders the configured `sap.m.Button` trigger.
+     *
+     * @param metadata The specific JSON schema properties for this action 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 action Button 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);
+
+        this.control = new Button({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            text: this.buildLabelBinding(metadata, bindingPath, modelName) as unknown as string,
+            type: this.actionConfig.buttonType,
+            icon: this.actionConfig.icon,
+            enabled: this.resolveEnabled(),
+            press: (oEvent: Event) => {
+                this.onPress(oEvent);
+            }
+        });
+
+        this.applyCommonDirectives(this.control, metadata, modelName);
+        return this.control;
+    }
+
+    /**
+     * Performs the action behind the trigger.
+     *
+     * Implementations read `this.metadata`, never a render-time closure: a policy effect replaces
+     * the metadata through `updateMetadata`, and a handler that captured the original object would
+     * act on a target the field no longer has.
+     *
+     * @param event The `sap.m.Button` press event.
+     */
+    protected abstract onPress(event: Event): void;
+
+    /**
+     * Builds the button's `text` binding: the bound value when it reads as a label, otherwise the
+     * configured fallback.
+     *
+     * @param metadata The action property metadata.
+     * @param bindingPath The JSON path bound to this control.
+     * @param modelName The UI5 JSONModel name.
+     * @returns {PropertyBindingInfo | string} The label binding descriptor.
+     */
+    protected buildLabelBinding(
+        metadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName: string
+    ): PropertyBindingInfo | string {
+        const fallbackLabel = metadata.ui?.label || I18n.getText(this.actionConfig.fallbackLabelKey);
+        return this.generateBindingInfo(bindingPath, modelName, undefined, {
+            formatter: (val: unknown) => this.resolveLabelText(val, fallbackLabel)
+        });
+    }
+
+    /**
+     * Chooses the label text for a bound value. Overridden where the bound value is the action's
+     * target rather than its caption.
+     *
+     * @param val The current bound value.
+     * @param fallbackLabel The configured fallback caption.
+     * @returns {string} The caption to paint on the button.
+     */
+    protected resolveLabelText(val: unknown, fallbackLabel: string): string {
+        return typeof val === "string" && val.trim() ? val.trim() : fallbackLabel;
+    }
+
+    /**
+     * Resolves whether the trigger is interactive. The default follows host editability, because a
+     * read-only host must not let the user mutate the form.
+     *
+     * @returns {boolean} True when the button should be enabled.
+     */
+    protected resolveEnabled(): boolean {
+        return this.isControlEditable();
+    }
+
+    /**
+     * Reports whether something other than this plugin owns the button's `enabled` state, in which
+     * case `applyState` must not overwrite it. The default is that the plugin owns it.
+     *
+     * @returns {boolean} True when `applyState` should leave `enabled` alone.
+     */
+    protected isEnabledStateExternallyOwned(): boolean {
+        return false;
+    }
+
+    /**
+     * Action buttons do not hold user data and never fail schema validation.
+     *
+     * @returns {{ isValid: boolean; errorMessage?: string }} Always `{ isValid: true }`.
+     */
+    public override validate(): { isValid: boolean; errorMessage?: string } {
+        return { isValid: true };
+    }
+
+    /**
+     * Action buttons have no bound value.
+     *
+     * @param sourceControl Optional runtime source control (e.g., cloned table cell).
+     * @returns {unknown} Always `null`.
+     */
+    protected getValue(sourceControl?: Control): unknown {
+        void sourceControl;
+        return null;
+    }
+
+    /**
+     * Updates the button's `enabled` state when `isEditable` or `readOnly` changes.
+     */
+    protected applyState(): void {
+        if (!this.control || !this.metadata || this.isEnabledStateExternallyOwned()) {
+            return;
+        }
+        (this.control as Button).setEnabled(this.resolveEnabled());
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/actions/ClearFormActionPlugin.ts

@@ -1,58 +1,87 @@
-/**
- * @file ClearFormActionPlugin.ts
- * @description A custom action plugin that renders a Button to reset the model data.
- */
-
-import { BasePlugin } from "../controls/BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import Button from "sap/m/Button";
-import Control from "sap/ui/core/Control";
-import JSONModel from "sap/ui/model/json/JSONModel";
-
-import Event from "sap/ui/base/Event";
-/**
- * A custom action plugin that renders a Button to reset the model data.
- * Demonstrates how to create functional action plugins that interact with the bound model.
- * 
- * @namespace nz.co.siliconst.ui5.metaui.plugins.actions
- * @public
- */
-export class ClearFormActionPlugin extends BasePlugin {
-    public render(fieldMetadata: IPropertyMetadata, bindingPath: string, modelName: string = "meta"): Control {
-        this.metadata = fieldMetadata;
-        
-        if (!this.isEditable) {
-            sap.ui.requireSync("sap/m/Text");
-            const TextControl = sap.ui.require("sap/m/Text");
-            this.control = new TextControl({ visible: false });
-            return this.control as Control;
-        }
-        
-        this.control = new Button({
-            text: fieldMetadata.ui?.label || "Clear Data",
-            type: "Reject",
-            icon: "sap-icon://delete",
-            press: (oEvent: Event) => {
-                const btn = oEvent.getSource() as Button;
-                const model = btn.getModel(modelName) as JSONModel;
-                if (model) {
-                    // Reset the entire model payload to an empty object
-                    model.setProperty("/", {});
-                }
-            }
-        });
-
-        return this.control as Control;
-    }
-
-    protected getValue(): unknown {
-        return null; // Actions do not store scalar values
-    }
-
-    protected applyState(): void {
-        if (this.control && this.metadata) {
-            if (!this.isEditable) return;
-            (this.control as Button).setEnabled(!this.metadata.ui?.readOnly);
-        }
-    }
-}
+/**
+ * @file ClearFormActionPlugin.ts
+ * @description Action plugin that renders a button to reset all fields in the current form model.
+ */
+
+import { ActionButtonPlugin, IActionButtonConfig } from "./ActionButtonPlugin";
+import Event from "sap/ui/base/Event";
+import JSONModel from "sap/ui/model/json/JSONModel";
+import { ButtonType } from "sap/m/library";
+import { isRecord } from "../../utils/TypeGuards";
+import { TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Plugin responsible for rendering a form reset button (`ui.widget = "clearButton"`).
+ * Resets all properties in the bound `JSONModel` to empty defaults and notifies the Engine.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.actions
+ * @internal
+ */
+export class ClearFormActionPlugin extends ActionButtonPlugin {
+    protected readonly actionConfig: IActionButtonConfig = {
+        fallbackLabelKey: TEXT_KEY.actionClearForm,
+        buttonType: ButtonType.Default,
+        icon: "sap-icon://clear-all"
+    };
+
+    /**
+     * Clears the bound form data.
+     *
+     * @param event The `sap.m.Button` press event.
+     */
+    protected onPress(event: Event): void {
+        void event;
+        this.clearFormModel();
+    }
+
+    /**
+     * Recursively resets a data value to its empty representation while preserving nested object keys.
+     *
+     * @param val The current property value.
+     * @returns {unknown} The cleared value.
+     */
+    private clearDataValue(val: unknown): unknown {
+        if (typeof val === "boolean") {
+            return false;
+        }
+        if (typeof val === "number" || val === null) {
+            return null;
+        }
+        if (Array.isArray(val)) {
+            return [];
+        }
+        if (isRecord(val)) {
+            const nested: Record<string, unknown> = {};
+            for (const [childKey, childVal] of Object.entries(val)) {
+                nested[childKey] = this.clearDataValue(childVal);
+            }
+            return nested;
+        }
+        return "";
+    }
+
+    /**
+     * Resets all top-level and nested keys in the bound `JSONModel` to empty values (`""`, `false`, `null`, `[]`),
+     * clears active validation errors, and triggers `notifyChange` so the Engine re-evaluates policies and state.
+     */
+    private clearFormModel(): void {
+        if (!this.control) {
+            return;
+        }
+        const model = (this.control.getModel(this.modelName) || this.engineContext?.getModel()) as
+            | JSONModel
+            | undefined;
+        if (!model) {
+            return;
+        }
+
+        const currentData = model.getData();
+        if (isRecord(currentData)) {
+            const cleared = this.clearDataValue(currentData) as Record<string, unknown>;
+            this.engineContext?.clearValidationErrors?.();
+            this.engineContext?.clearValidationPrefix?.("");
+            model.setData(cleared);
+            this.notifyChange();
+        }
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/actions/SubmitFormActionPlugin.ts

@@ -1,52 +1,36 @@
-/**
- * @file SubmitFormActionPlugin.ts
- * @description A custom action plugin that triggers form submission.
- */
-
-import { BasePlugin } from "../controls/BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import Button from "sap/m/Button";
-import Control from "sap/ui/core/Control";
-import Core from "sap/ui/core/Core";
-
-/**
- * Renders a Button that requests the host container to execute its submit flow.
- * 
- * @namespace nz.co.siliconst.ui5.metaui.plugins.actions
- * @public
- */
-export class SubmitFormActionPlugin extends BasePlugin {
-    public render(fieldMetadata: IPropertyMetadata, bindingPath: string, modelName: string = "meta"): Control {
-        this.metadata = fieldMetadata;
-        
-        if (!this.isEditable) {
-            sap.ui.requireSync("sap/m/Text");
-            const TextControl = sap.ui.require("sap/m/Text");
-            this.control = new TextControl({ visible: false });
-            return this.control as Control;
-        }
-        
-        this.control = new Button({
-            text: fieldMetadata.ui?.label || "Submit",
-            type: "Emphasized",
-            icon: "sap-icon://save",
-            press: () => {
-                // Fire an event that the GeneratorHost or LayoutManager listens to
-                Core.getEventBus().publish("MetaUI", "TriggerSubmit", {});
-            }
-        });
-
-        return this.control as Control;
-    }
-
-    protected getValue(): unknown {
-        return null;
-    }
-
-    protected applyState(): void {
-        if (this.control && this.metadata) {
-            if (!this.isEditable) return;
-            (this.control as Button).setEnabled(!this.metadata.ui?.readOnly);
-        }
-    }
-}
+/**
+ * @file SubmitFormActionPlugin.ts
+ * @description Action plugin that renders an Emphasized Submit button and invokes the Engine's submit hook.
+ */
+
+import { ActionButtonPlugin, IActionButtonConfig } from "./ActionButtonPlugin";
+import Event from "sap/ui/base/Event";
+import { ButtonType } from "sap/m/library";
+import { TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Plugin responsible for rendering an inline form submit trigger (`ui.widget = "submitButton"`).
+ * Invokes `this.engineContext.onSubmit()` when pressed.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.actions
+ * @internal
+ */
+export class SubmitFormActionPlugin extends ActionButtonPlugin {
+    protected readonly actionConfig: IActionButtonConfig = {
+        fallbackLabelKey: TEXT_KEY.actionSubmit,
+        buttonType: ButtonType.Emphasized,
+        icon: "sap-icon://accept"
+    };
+
+    /**
+     * Triggers the host submission pipeline.
+     *
+     * @param event The `sap.m.Button` press event.
+     */
+    protected onPress(event: Event): void {
+        void event;
+        if (this.engineContext?.onSubmit) {
+            this.engineContext.onSubmit();
+        }
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/actions/UrlNavigationActionPlugin.ts

@@ -1,45 +1,126 @@
-/**
- * @file UrlNavigationActionPlugin.ts
- * @description A custom action plugin that navigates to a URL.
- */
-
-import { BasePlugin } from "../controls/BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import Button from "sap/m/Button";
-import Control from "sap/ui/core/Control";
-import * as library from "sap/m/library";
-const URLHelper = library.URLHelper;
-
-/**
- * Renders a Button that triggers a redirect to an external URL (defined in args).
- * 
- * @namespace nz.co.siliconst.ui5.metaui.plugins.actions
- * @public
- */
-export class UrlNavigationActionPlugin extends BasePlugin {
-    public render(fieldMetadata: IPropertyMetadata, bindingPath: string, modelName: string = "meta"): Control {
-        this.metadata = fieldMetadata;
-
-        this.control = new Button({
-            text: fieldMetadata.ui?.label || "Open Link",
-            icon: "sap-icon://action",
-            press: () => {
-                // In a real scenario, the URL might come from the payload or from schema args
-                const targetUrl = fieldMetadata.ui?.args || "https://sap.com";
-                URLHelper.redirect(targetUrl as string, true); // true = open in new window
-            }
-        });
-
-        return this.control as Control;
-    }
-
-    protected getValue(): unknown {
-        return null;
-    }
-
-    protected applyState(): void {
-        if (this.control && this.metadata) {
-            (this.control as Button).setEnabled(!this.metadata.ui?.readOnly);
-        }
-    }
-}
+/**
+ * @file UrlNavigationActionPlugin.ts
+ * @description Action plugin that renders a button to navigate to a validated URL.
+ */
+
+import { ActionButtonPlugin, IActionButtonConfig } from "./ActionButtonPlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import Control from "sap/ui/core/Control";
+import Event from "sap/ui/base/Event";
+import JSONModel from "sap/ui/model/json/JSONModel";
+import { ButtonType, URLHelper } from "sap/m/library";
+import { UrlValidator } from "../../utils/UrlValidator";
+import { Logger } from "../../utils/Logger";
+import { TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Plugin responsible for rendering a URL navigation action button (`ui.widget = "urlButton"`).
+ * Validates the target URL protocol via `UrlValidator.isSafeNavigationUrl` before redirecting.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.actions
+ * @internal
+ */
+export class UrlNavigationActionPlugin extends ActionButtonPlugin {
+    protected readonly actionConfig: IActionButtonConfig = {
+        fallbackLabelKey: TEXT_KEY.actionOpenLink,
+        buttonType: ButtonType.Default,
+        icon: "sap-icon://action"
+    };
+
+    /**
+     * This button opens a URL in a new tab and mutates nothing, so it is a navigation affordance exactly like
+     * `LinkPlugin`: a read-only host must not make the target unreachable. The mutating action buttons
+     * (`SubmitFormActionPlugin`, `ClearFormActionPlugin`) deliberately keep the default and stay disabled.
+     */
+    protected override readonly isNavigationAffordance: boolean = true;
+
+    /**
+     * Opens the resolved target URL in a new tab, refusing anything the URL policy rejects.
+     *
+     * @param event The `sap.m.Button` press event.
+     */
+    protected onPress(event: Event): void {
+        const src = (event.getSource() as Control | undefined) ?? this.control;
+        const rawUrl = this.metadata ? this.resolveTargetUrl(this.metadata, src) : undefined;
+        if (UrlValidator.isSafeNavigationUrl(rawUrl)) {
+            URLHelper.redirect(rawUrl.trim(), true);
+            return;
+        }
+        Logger.warn(`Blocked navigation to unsafe or empty URL: '${String(rawUrl)}'`, undefined, "UrlNavigationActionPlugin");
+    }
+
+    /**
+     * The bound value here is the navigation target, not a caption, so a bound value that reads as a
+     * safe URL must not be painted on the button.
+     *
+     * @param val The current bound value.
+     * @param fallbackLabel The configured fallback caption.
+     * @returns {string} The caption to paint on the button.
+     */
+    protected override resolveLabelText(val: unknown, fallbackLabel: string): string {
+        if (typeof val !== "string") {
+            return fallbackLabel;
+        }
+        const labelText: string = val.trim();
+        return labelText && !UrlValidator.isSafeNavigationUrl(val) ? labelText : fallbackLabel;
+    }
+
+    /**
+     * Navigation stays available under `readOnly` and in display mode; only an explicit
+     * `ui.enabled: false` switches it off.
+     *
+     * @returns {boolean} True when the affordance should remain clickable.
+     */
+    protected override resolveEnabled(): boolean {
+        return this.isAffordanceEnabled();
+    }
+
+    /**
+     * An explicit `ui.enabledOn` expression is bound onto the button by `applyCommonDirectives` and
+     * always wins, so `applyState` must not overwrite it.
+     *
+     * @returns {boolean} True when an `ui.enabledOn` expression owns the enabled state.
+     */
+    protected override isEnabledStateExternallyOwned(): boolean {
+        return Boolean(this.metadata?.ui?.enabledOn);
+    }
+
+    /**
+     * Resolves the target URL from either the bound `JSONModel` property, `metadata.ui.options.url`, or `metadata.default`.
+     *
+     * @param metadata The action property metadata.
+     * @param sourceControl Optional runtime source control (e.g., cloned table cell).
+     * @returns {unknown} The candidate URL string.
+     */
+    private resolveTargetUrl(metadata: IPropertyMetadata, sourceControl?: Control): unknown {
+        const target = sourceControl ?? this.control;
+        if (target) {
+            const model = (target.getModel(this.modelName) || this.engineContext?.getModel()) as
+                | JSONModel
+                | undefined;
+            if (model) {
+                const boundVal = model.getProperty(this.resolveAbsolutePath(target));
+                if (typeof boundVal === "string" && UrlValidator.isSafeNavigationUrl(boundVal)) {
+                    return boundVal;
+                }
+            }
+        }
+        if (metadata.ui?.options && typeof metadata.ui.options.url === "string") {
+            return metadata.ui.options.url;
+        }
+        if (typeof metadata.ui?.args === "string") {
+            return metadata.ui.args;
+        }
+        return metadata.default;
+    }
+
+    /**
+     * Retrieves the resolved target URL string.
+     *
+     * @param sourceControl Optional runtime source control (e.g., cloned table cell).
+     * @returns {unknown} The target URL string or `null`.
+     */
+    protected override getValue(sourceControl?: Control): unknown {
+        return this.metadata ? this.resolveTargetUrl(this.metadata, sourceControl) : null;
+    }
+}