@siliconst/metaui 1.4.44 → 2.0.0

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

@@ -0,0 +1,301 @@
+/**
+ * @file NestedDialogPlugin.ts
+ * @description Shared abstract base class for nested modal dialog button plugins (ObjectPlugin, ArrayPlugin, ReferencePlugin).
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IPropertyMetadata, ISchema, IUIDirective } from "../../interfaces/ISchema";
+import Button from "sap/m/Button";
+import { ButtonType } from "sap/m/library";
+import Control from "sap/ui/core/Control";
+import JSONModel from "sap/ui/model/json/JSONModel";
+import Event from "sap/ui/base/Event";
+import { PayloadValidator } from "../../core/PayloadValidator";
+import { deepClone } from "../../utils/TypeGuards";
+import { I18n, MetaUITextKey, TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Resolved sub-schema and modal dialog configuration for a nested dialog launch.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export interface INestedDialogDescriptor {
+    title: string;
+    subSchema: ISchema;
+    isArrayRoot: boolean;
+}
+
+/**
+ * Shared abstract base class for `ObjectPlugin`, `ArrayPlugin`, and `ReferencePlugin`.
+ * Consolidates trigger `Button` rendering, modal `DynamicHost` dialog launching, recursive `PayloadValidator`
+ * validation, model value lookup, visual `ButtonType.Reject` error state, and `applyState`.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export abstract class NestedDialogPlugin extends BasePlugin {
+    /**
+     * Bundle key of the tooltip shown on the trigger button when the nested payload is invalid and the
+     * validator supplied no reason of its own. A key rather than a string, so the text is resolved against
+     * the session locale at the moment it is rendered instead of at construction time.
+     */
+    protected abstract readonly defaultErrorTooltipKey: MetaUITextKey;
+    protected abstract readonly emptyFallbackValue: unknown;
+    protected override readonly isNavigationAffordance: boolean = true;
+
+    /**
+     * Builds the trigger button's caption: `Edit <label>` while editable, `View <label>` otherwise.
+     *
+     * The label is a placeholder value rather than a concatenated fragment because languages order the
+     * two parts differently — German renders `{0} bearbeiten`, putting the verb last.
+     *
+     * @param label The resolved field label.
+     * @param canEdit True when the nested dialog will open in edit mode.
+     * @returns {string} The localized button caption.
+     */
+    private buildTriggerText(label: string, canEdit: boolean): string {
+        return I18n.getText(canEdit ? TEXT_KEY.nestedEdit : TEXT_KEY.nestedView, [label]);
+    }
+
+    /**
+     * Resolves the default label for the trigger button when `metadata.ui.label` is omitted.
+     *
+     * @param metadata The property metadata.
+     * @returns {string} The button label stem.
+     */
+    protected abstract getDefaultLabel(metadata: IPropertyMetadata): string;
+
+    /**
+     * Resolves the SAP icon URI for the trigger button based on current editability.
+     *
+     * @param canEdit True if the control is currently editable.
+     * @returns {string} The SAP icon URI.
+     */
+    protected abstract getButtonIcon(canEdit: boolean): string;
+
+    /**
+     * Builds the modal `ISchema` descriptor and dialog title for the nested `DynamicHost`.
+     *
+     * @param metadata The property metadata.
+     * @returns {INestedDialogDescriptor | null} The resolved dialog descriptor, or `null` to abort opening.
+     */
+    protected abstract buildDialogDescriptor(metadata: IPropertyMetadata): INestedDialogDescriptor | null;
+
+    /**
+     * Coerces the current raw model value before passing it into the nested `DynamicHost`.
+     *
+     * @param rawCurrent The raw value read from the parent `JSONModel`.
+     * @returns {unknown} The normalized initial payload for the nested editor.
+     */
+    protected coerceCurrentData(rawCurrent: unknown): unknown {
+        return rawCurrent;
+    }
+
+    /**
+     * Coerces the extracted payload returned by the nested `DynamicHost` before writing back to the parent `JSONModel`.
+     *
+     * @param extractedData The payload emitted by the nested `DynamicHost`.
+     * @returns {unknown} The coerced payload to persist.
+     */
+    protected coerceSavedData(extractedData: unknown): unknown {
+        return extractedData;
+    }
+
+    /**
+     * Carries the property's `ui` directive block onto the modal sub-schema root so that `labelSpan`,
+     * `controlProps` and `layoutBudget` govern the dialog exactly as they govern the inline rendering.
+     * Mirrors `ArraySubSchemaFactory.build`, including its read-only propagation.
+     *
+     * @param metadata The nested property metadata.
+     * @param inheritedUi Optional `ui` block already declared on a resolved `$ref` target, which the
+     *                    property-level directives override key by key.
+     * @returns {IUIDirective | undefined} The sub-schema root `ui` block, or `undefined` when none applies.
+     */
+    protected buildSubSchemaUi(metadata: IPropertyMetadata, inheritedUi?: IUIDirective): IUIDirective | undefined {
+        const merged: IUIDirective | undefined =
+            inheritedUi || metadata.ui
+                ? { ...(inheritedUi ? deepClone(inheritedUi) : {}), ...(metadata.ui ? deepClone(metadata.ui) : {}) }
+                : undefined;
+        if (metadata.readOnly || merged?.readOnly) {
+            return { ...(merged || {}), readOnly: true };
+        }
+        return merged;
+    }
+
+    /**
+     * Renders a `sap.m.Button` that opens a nested `DynamicHost` dialog when pressed.
+     *
+     * @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 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);
+
+        const label = this.getDefaultLabel(metadata);
+        const canEdit = this.isControlEditable();
+        const btnText = metadata.ui?.dialogButtonText || this.buildTriggerText(label, canEdit);
+        const textBinding =
+            !this.isEditable && !metadata.ui?.dialogButtonText
+                ? this.generateBindingInfo(bindingPath, modelName, undefined, {
+                      formatter: (val: unknown) => {
+                          if (Array.isArray(val)) {
+                              return I18n.getText(TEXT_KEY.nestedViewSummary, [label, val.length]);
+                          }
+                          if (val && typeof val === "object") {
+                              const summary = Object.values(val as Record<string, unknown>).join(", ");
+                              return summary
+                                  ? I18n.getText(TEXT_KEY.nestedViewSummary, [label, summary])
+                                  : I18n.getText(TEXT_KEY.nestedView, [label]);
+                          }
+                          return I18n.getText(TEXT_KEY.nestedView, [label]);
+                      }
+                  })
+                : btnText;
+
+        this.control = new Button({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            text: textBinding as unknown as string,
+            icon: this.getButtonIcon(canEdit),
+            press: (oEvent: Event) => {
+                this.openNestedDialog(oEvent.getSource() as Button, metadata);
+            }
+        });
+
+        this.applyCommonDirectives(this.control, metadata, modelName);
+        return this.control;
+    }
+
+    /**
+     * Opens a modal `DynamicHost` dialog populated with the resolved sub-schema and current model data.
+     *
+     * @param btn The clicked `sap.m.Button` instance.
+     * @param metadata The property metadata.
+     */
+    protected openNestedDialog(btn: Button, metadata: IPropertyMetadata): void {
+        const descriptor = this.buildDialogDescriptor(metadata);
+        if (!descriptor) {
+            return;
+        }
+
+        const model = (btn.getModel(this.modelName) || this.engineContext?.getModel()) as JSONModel | undefined;
+        if (!model) {
+            return;
+        }
+
+        const absolutePath = this.resolveAbsolutePath(btn);
+        const currentData = this.coerceCurrentData(model.getProperty(absolutePath));
+
+        this.openNestedEditorDialog({
+            title: descriptor.title,
+            subSchema: descriptor.subSchema,
+            currentData,
+            definitions: this.engineContext?.getSchemaDefinitions(),
+            editable: this.isControlEditable(),
+            layoutBudget: this.resolveNestedLayoutBudget(metadata),
+            isArrayRoot: descriptor.isArrayRoot,
+            onSave: (extractedData: unknown) => {
+                model.setProperty(absolutePath, this.coerceSavedData(extractedData));
+                this.notifyChange(btn.getId());
+            }
+        });
+    }
+
+    /**
+     * Resolves the layout budget the nested modal host runs under: the author's own `ui.layoutBudget`
+     * on this property when declared, otherwise the budget in force on the owning host.
+     *
+     * The budget used to reach the dialog only because `LayoutScorer` wrote the effective budget onto
+     * every schema node and {@link NestedDialogPlugin.buildSubSchemaUi} copied that node's `ui` block
+     * onto the modal sub-schema. Reading it from the engine context instead keeps the layout engine's
+     * working state out of the consumer's schema.
+     *
+     * @param metadata The nested property metadata.
+     * @returns {number} The budget for the nested host; 0 disables inline sub-layouts inside the dialog.
+     */
+    protected resolveNestedLayoutBudget(metadata: IPropertyMetadata): number {
+        const declared = metadata.ui?.layoutBudget;
+        if (typeof declared === "number" && declared > 0) {
+            return declared;
+        }
+        return this.engineContext?.getLayoutBudget?.() ?? 0;
+    }
+
+    /**
+     * Recursively validates the nested payload against its schema rules via `PayloadValidator`.
+     *
+     * @param sourceControl Optional cloned row control to validate when bound inside a `TableLayout`.
+     * @returns {{ isValid: boolean; errorMessage?: string }} The validation outcome.
+     */
+    public override validate(sourceControl?: Control): { isValid: boolean; errorMessage?: string } {
+        const target = sourceControl || this.control;
+        if (!target || !this.metadata || !this.isTargetVisible(sourceControl)) {
+            return { isValid: true };
+        }
+        return PayloadValidator.validateTree(
+            this.metadata,
+            this.getValue(target),
+            (ref) => this.engineContext?.getSchemaDefinition(ref) ?? null
+        );
+    }
+
+    /**
+     * Retrieves the current nested payload from the bound `JSONModel`.
+     *
+     * @param sourceControl Optional cloned row control to read from when bound inside a `TableLayout`.
+     * @returns {unknown} The nested data payload.
+     */
+    protected getValue(sourceControl?: Control): unknown {
+        const target = sourceControl || this.control;
+        if (!target) {
+            return this.emptyFallbackValue;
+        }
+        const model = (target.getModel(this.modelName) || this.engineContext?.getModel()) as JSONModel | undefined;
+        return model ? model.getProperty(this.resolveAbsolutePath(target)) : this.emptyFallbackValue;
+    }
+
+    /**
+     * Reflects nested validation errors visually on the trigger `Button` via `ButtonType.Reject` and tooltip.
+     *
+     * @param isValid True if the nested payload is valid.
+     * @param errorMessage Optional validation error message.
+     */
+    public override setVisualValidationState(isValid: boolean, errorMessage?: string): void {
+        if (this.control instanceof Button) {
+            this.control.setType(isValid ? ButtonType.Default : ButtonType.Reject);
+            this.control.setTooltip(
+                isValid
+                    ? this.metadata?.description || ""
+                    : errorMessage || I18n.getText(this.defaultErrorTooltipKey)
+            );
+        }
+    }
+
+    /**
+     * Updates the trigger button text and icon when `isEditable` or `readOnly` state changes.
+     */
+    protected applyState(): void {
+        if (this.control && this.metadata) {
+            const btn = this.control as Button;
+            const label = this.getDefaultLabel(this.metadata);
+            const canEdit = this.isControlEditable();
+            if (this.isEditable || this.metadata.ui?.dialogButtonText) {
+                btn.setText(this.metadata.ui?.dialogButtonText || this.buildTriggerText(label, canEdit));
+            }
+            btn.setIcon(this.getButtonIcon(canEdit));
+            if (!this.metadata.ui?.enabledOn) {
+                btn.setEnabled(this.isAffordanceEnabled());
+            }
+        }
+    }
+}

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

@@ -1,121 +1,167 @@
-/**
- * @file NumberPlugin.ts
- * @description Renders a sap.m.Input configured for generic dynamic numeric data.
- */
-
-import { BasePlugin } from "./BasePlugin";
-import { IPropertyMetadata } from "../../interfaces/ISchema";
-import Input from "sap/m/Input";
-import Control from "sap/ui/core/Control";
-import TextControl from "sap/m/Text";
-import Float from "sap/ui/model/type/Float";
-import Integer from "sap/ui/model/type/Integer";
-import StepInput from "sap/m/StepInput";
-
-/**
- * Handles rendering and logic for dynamic numeric inputs.
- */
-export class NumberPlugin extends BasePlugin {
-    /**
-     * Renders a `sap.m.Input` component for numeric evaluation with dynamic Float type.
-     * 
-     * @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 Input 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;
-
-        if (!this.isEditable) {
-            this.control = new TextControl({
-                id: this.generateStableId(engineScopeId, bindingPath),
-                text: this.generateBindingInfo(bindingPath, modelName)
-            });
-            this.applyCommonDirectives(this.control, fieldMetadata, modelName);
-            return this.control as Control;
-        }
-
-        let typeInstance;
-        if (fieldMetadata.type === "integer") {
-            typeInstance = new Integer({ groupingEnabled: false });
-        } else {
-            typeInstance = new Float({
-                groupingEnabled: false,
-                minFractionDigits: fieldMetadata.scale !== undefined ? fieldMetadata.scale : 0,
-                maxFractionDigits: fieldMetadata.scale !== undefined ? fieldMetadata.scale : 9
-            });
-        }
-
-        const onChangeFn = (oEvent: sap.ui.base.Event) => {
-            const val = (oEvent as any).getParameter("value");
-            const result = this.validate();
-            if (this.onChange) {
-                this.onChange(result.isValid, this.fieldKey, result.errorMessage);
-            }
-        };
-
-        if (fieldMetadata.ui?.widget === "stepInput") {
-            this.control = new StepInput({
-                id: this.generateStableId(engineScopeId, bindingPath),
-                value: {
-                    path: bindingPath,
-                    model: modelName,
-                    type: typeInstance
-                },
-                editable: !fieldMetadata.ui?.readOnly,
-                required: !!fieldMetadata.required,
-                change: onChangeFn
-            });
-        } else {
-            this.control = new Input({
-                id: this.generateStableId(engineScopeId, bindingPath),
-                value: {
-                    path: bindingPath,
-                    model: modelName,
-                    type: typeInstance
-                },
-                type: "Number",
-                editable: !fieldMetadata.ui?.readOnly,
-                required: !!fieldMetadata.required,
-                change: onChangeFn
-            });
-        }
-
-        this.applyCommonDirectives(this.control, fieldMetadata, modelName);
-
-        return this.control as Control;
-    }
-
-    /**
-     * Retrieves the current numeric state.
-     * @returns {unknown} The numeric value.
-     */
-    protected getValue(): unknown {
-        if (!this.control) return null;
-        // In UI5, Input.getProperty('value') returns a string. We must parse it if it's bound.
-        // However, we can also extract it directly from the binding.
-        const input = this.control as any;
-        const binding = input.getBinding("value");
-        if (binding && typeof binding.getValue === "function") {
-            return binding.getValue();
-        }
-        return input.getProperty('value');
-    }
-
-    /**
-     * Applies dynamic read-only state.
-     */
-    protected applyState(): void {
-        if (this.control && this.metadata) {
-            if (!this.isEditable) return;
-            const input = this.control as any;
-            input.setEditable(!this.metadata.ui?.readOnly);
-            input.setRequired(!!this.metadata.required);
-        }
-    }
-}
+/**
+ * @file NumberPlugin.ts
+ * @description Renders a numeric sap.m.Input control with numeric coercion and validation.
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IPropertyMetadata } from "../../interfaces/ISchema";
+import Input from "sap/m/Input";
+import Control from "sap/ui/core/Control";
+import Event from "sap/ui/base/Event";
+import { InputType } from "sap/m/library";
+import { I18n, TEXT_KEY } from "../../utils/I18n";
+
+/**
+ * Handles rendering logic for numeric (`number` and `integer`) properties.
+ * Coerces valid numbers into the underlying `JSONModel` and flags unparseable input as invalid.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.plugins.controls
+ * @internal
+ */
+export class NumberPlugin extends BasePlugin {
+    private hasUnparseableInput: boolean = false;
+
+    /**
+     * Renders a `sap.m.Input` control with `type: InputType.Number`.
+     *
+     * @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 numeric Input 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.hasUnparseableInput = false;
+
+        if (!this.isEditable) {
+            return this.createDisplayText(engineScopeId, bindingPath);
+        }
+
+        const hasFormatter = Boolean(
+            metadata.ui?.formatter || (metadata.ui?.formatters && metadata.ui.formatters.length > 0)
+        );
+
+        this.control = new Input({
+            id: this.generateStableId(engineScopeId, bindingPath),
+            type: hasFormatter ? InputType.Text : InputType.Number,
+            value: this.generateBindingInfo(bindingPath, modelName) as unknown as string,
+            placeholder: metadata.ui?.placeholder || "",
+            required: this.isRequired(),
+            change: (oEvent: Event) => {
+                const input = oEvent.getSource() as Input;
+                const rawVal = input.getValue().trim();
+                const targetPath = this.resolveAbsolutePath(input);
+                const cleanPath = targetPath.replace(/^\//, "") || this.fieldKey || "";
+
+                // Explicitly coerce string input into a native JavaScript number in the JSONModel
+                if (rawVal === "") {
+                    this.hasUnparseableInput = false;
+                    this.invalidParsePaths.delete(cleanPath);
+                    input.data("metauiParseInvalid", null);
+                    const dynReq = this.getDynamicRequiredOverride(input);
+                    const effectiveReq = dynReq !== undefined ? dynReq : this.isRequired();
+                    const emptyVal = metadata.nullable === false && !effectiveReq ? undefined : null;
+                    this.commitValue(input, emptyVal);
+                } else {
+                    const parsedInput = this.hasPresentationalFormatter()
+                        ? this.resolveModelWriteValue(rawVal)
+                        : rawVal;
+                    const numVal = typeof parsedInput === "number" ? parsedInput : Number(parsedInput);
+                    if (Number.isNaN(numVal)) {
+                        this.hasUnparseableInput = true;
+                        this.invalidParsePaths.set(cleanPath, I18n.getText(TEXT_KEY.numberParseError));
+                        input.data("metauiParseInvalid", true);
+                    } else if (metadata.type === "integer" && !Number.isInteger(numVal)) {
+                        this.hasUnparseableInput = true;
+                        this.invalidParsePaths.set(cleanPath, I18n.getText(TEXT_KEY.integerParseError));
+                        input.data("metauiParseInvalid", true);
+                    } else {
+                        this.hasUnparseableInput = false;
+                        this.invalidParsePaths.delete(cleanPath);
+                        input.data("metauiParseInvalid", null);
+                        this.commitValue(input, numVal);
+                    }
+                }
+
+                this.notifyChange(input.getId());
+            }
+        });
+
+        this.applyCommonDirectives(this.control, metadata, modelName);
+        return this.control;
+    }
+
+    /**
+     * Returns a parse error message when the user input is an unparseable number (or non-integer for `integer`).
+     *
+     * @param sourceControl Optional runtime source control (e.g., cloned table cell).
+     * @returns {string | undefined} The parse error message if invalid, otherwise `undefined`.
+     */
+    protected override getParseError(sourceControl?: Control): string | undefined {
+        if (!sourceControl && this.hasUnparseableInput && this.metadata) {
+            return this.metadata.type === "integer"
+                ? I18n.getText(TEXT_KEY.integerParseError)
+                : I18n.getText(TEXT_KEY.numberParseError);
+        }
+        return undefined;
+    }
+
+    /**
+     * Clears any visual error state and resets parse error flags on the numeric plugin.
+     */
+    public override clearError(): void {
+        this.hasUnparseableInput = false;
+        super.clearError();
+    }
+
+    /**
+     * Retrieves the current numeric value from the `sap.m.Input` control.
+     *
+     * @param sourceControl Optional runtime source control (e.g., cloned table cell).
+     * @returns {unknown} The parsed number, `null`/`undefined` if empty, or raw string if unparseable.
+     */
+    protected getValue(sourceControl?: Control): unknown {
+        if (!this.isEditable) {
+            return this.getModelValue(sourceControl);
+        }
+        const target = (sourceControl ?? this.control) as Input | undefined;
+        if (!target || typeof target.getValue !== "function") {
+            return this.getModelValue(target);
+        }
+        const raw = target.getValue().trim();
+        if (raw === "") {
+            const modelVal = this.getModelValue(target);
+            if (!target.getDomRef()) {
+                return modelVal;
+            }
+            return modelVal === undefined ? undefined : null;
+        }
+        const candidate = this.hasPresentationalFormatter() ? this.resolveModelWriteValue(raw) : raw;
+        const parsed = typeof candidate === "number" ? candidate : Number(candidate);
+        if (Number.isNaN(parsed)) {
+            return raw;
+        }
+        return parsed;
+    }
+
+    /**
+     * Applies dynamic `readOnly`, `required`, and `placeholder` state updates to the Input.
+     */
+    protected applyState(): void {
+        if (!this.control || !this.metadata || !this.isEditable) {
+            return;
+        }
+        const input = this.control as Input;
+        input.setEditable(this.isControlEditable());
+        input.setRequired(this.isRequired());
+        input.setPlaceholder(this.metadata.ui?.placeholder || "");
+    }
+}