@siliconst/metaui 1.4.44 → 2.0.0

package/src/nz/co/siliconst/ui5/metaui/layouts/WizardLayout.ts

@@ -1,135 +1,327 @@
-/**
- * @file WizardLayout.ts
- * @description Generates a fully responsive SAP Fiori Wizard layout.
- */
-
-import Wizard from "sap/m/Wizard";
-import WizardStep from "sap/m/WizardStep";
-import SimpleForm from "sap/ui/layout/form/SimpleForm";
-import Label from "sap/m/Label";
-import VBox from "sap/m/VBox";
-import { IPropertyMetadata, ISchema, ILayoutElement } from "../interfaces/ISchema";
-import { ILayoutManager } from "../interfaces/ILayoutManager";
-import { Engine } from "../core/Engine";
-import { SchemaNormalizer } from "../core/SchemaNormalizer";
-import { Logger } from "../utils/Logger";
-import Control from "sap/ui/core/Control";
-
-/**
- * Layout Manager responsible for generating a responsive SAP Fiori Wizard.
- * It segments the schema fields into discrete Wizard Steps based on `uiLayout` elements 
- * of type `Group` or `WizardStep`.
- * 
- * @namespace nz.co.siliconst.ui5.metaui.layouts
- * @public
- */
-export class WizardLayout implements ILayoutManager {
-    /**
-     * Renders the JSON Schema properties into a paginated UI5 Wizard using uiLayout.
-     * 
-     * @param schema The active JSON schema object.
-     * @param modelName The bound UI5 model name.
-     * @param engine The central orchestrator for delegating plugin generation.
-     * @param onSubmit Hook executed when the Wizard's native 'complete' event is fired.
-     * @returns {Control} The generated sap.m.Wizard control.
-     */
-    public render(schema: ISchema, modelName: string, engine: Engine, onSubmit?: () => void): Control {
-        const wizard = new Wizard({
-            renderMode: "Page",
-            showNextButton: true,
-            complete: function() {
-                if (onSubmit) onSubmit();
-            }
-        });
-
-        if (!schema.uiLayout || !Array.isArray(schema.uiLayout)) {
-            Logger.warn("[MetaUI] Missing 'uiLayout' array in wizard schema. Wizard will not render any steps.");
-            return wizard;
-        }
-
-        schema.uiLayout.forEach((element: ILayoutElement) => {
-            if (element.type === "Group" || element.type === "WizardStep") {
-                const step = new WizardStep({
-                    title: element.label || "Step",
-                    validated: true // The PipelineManager handles global validation, wizard step validation can be local later
-                });
-
-                const form = new SimpleForm({
-                    editable: true,
-                    layout: "ResponsiveGridLayout",
-                    labelSpanXL: 4, labelSpanL: 4, labelSpanM: 4, labelSpanS: 12,
-                    adjustLabelSpan: false,
-                    emptySpanXL: 0, emptySpanL: 0, emptySpanM: 0, emptySpanS: 0,
-                    columnsXL: 1, columnsL: 1, columnsM: 1,
-                    singleContainerFullSize: false
-                });
-                
-                if (element.elements && Array.isArray(element.elements)) {
-                    element.elements.forEach(childElement => {
-                        this._renderElementInForm(form, childElement, schema, modelName, engine);
-                    });
-                }
-
-                step.addContent(form);
-                wizard.addStep(step);
-            } else {
-                Logger.warn(`[MetaUI] Top-level element '${element.type}' inside WizardLayout must be 'Group' or 'WizardStep'.`, "", "WizardLayout");
-            }
-        });
-
-        return wizard;
-    }
-
-    /**
-     * Synthesizes a field into the wizard step form.
-     * @param form The SimpleForm belonging to the step.
-     * @param element The layout element definition.
-     * @param schema The schema reference.
-     * @param modelName The UI5 data model name.
-     * @param engine The core Engine instance.
-     */
-    private _renderElementInForm(form: SimpleForm, element: ILayoutElement, schema: ISchema, modelName: string, engine: Engine): void {
-        if (element.type === "Control") {
-            if (!element.scope || !element.scope.startsWith("#/properties/")) {
-                Logger.error(`[MetaUI] Invalid scope '${element.scope}' in uiLayout Control.`, "", "WizardLayout");
-                return;
-            }
-            
-            const { meta, bindingPath, propKey } = SchemaNormalizer.resolveScope(schema, element.scope);
-            
-            if (!meta) {
-                Logger.error(`[MetaUI] Property '${propKey}' not found in schema definitions.`, "", "WizardLayout");
-                return;
-            }
-
-            try {
-                const labelText = element.label || meta.ui?.label || propKey;
-                const label = new Label({
-                    text: labelText,
-                    required: meta.required
-                });
-
-                const effectiveMeta = { ...meta };
-                if (element.widget) {
-                    effectiveMeta.ui = { ...meta.ui, widget: element.widget };
-                }
-
-                const control = engine.generateField(effectiveMeta, `/${bindingPath}`, modelName);
-
-                if (effectiveMeta.ui?.fullWidth) {
-                    sap.ui.require(["sap/ui/layout/GridData"], (GridData: typeof import("sap/ui/layout/GridData").default) => {
-                        control.setLayoutData(new GridData({ span: "XL12 L12 M12 S12" }));
-                    });
-                }
-
-                form.addContent(label);
-                form.addContent(control);
-            } catch (error) {
-                Logger.error(`[MetaUI] Failed to render Wizard field ${propKey}`, (error as Error).message, "WizardLayout");
-                form.addContent(new Label({ text: propKey }));
-            }
-        } else {
-            Logger.warn(`[MetaUI] Nested groups within Wizard steps are not fully supported in SimpleForm yet.`, "", "WizardLayout");
-        }
-    }
-}
+/**
+ * @file WizardLayout.ts
+ * @description MetaUI custom step-by-step wizard navigator.
+ *
+ * Architecture Decision:
+ * SAP's sap.m.Wizard in renderMode "Page" requires a NavContainer ancestor in the DOM,
+ * which MetaUI's GeneratorHost VBox does not provide. Using sap.m.Wizard in the default
+ * "Scroll" mode renders ALL steps simultaneously, which is not desired behavior.
+ *
+ * Solution: Implement a fully custom step navigator using plain VBox/HBox/Button controls.
+ * This gives MetaUI complete control over step visibility, per-step field validation,
+ * and the beforeLayoutSectionChange async event API — with no dependency on the broken
+ * Wizard container API.
+ */
+
+import SimpleForm from "sap/ui/layout/form/SimpleForm";
+import VBox from "sap/m/VBox";
+import HBox from "sap/m/HBox";
+import Button from "sap/m/Button";
+import ProgressIndicator from "sap/m/ProgressIndicator";
+import MTitle from "sap/m/Title";
+import Text from "sap/m/Text";
+import Control from "sap/ui/core/Control";
+import { TitleLevel, ValueState } from "sap/ui/core/library";
+import { ButtonType, FlexAlignItems, FlexJustifyContent } from "sap/m/library";
+import { ISchema, ILayoutElement } from "../interfaces/ISchema";
+import { IPlugin } from "../interfaces/IPlugin";
+import { ILayoutManager } from "../interfaces/ILayoutManager";
+import { Engine } from "../core/Engine";
+import { WizardStepRenderer } from "./WizardStepRenderer";
+import { AccessibilityUtil } from "../utils/AccessibilityUtil";
+import { Logger } from "../utils/Logger";
+import { I18n, TEXT_KEY } from "../utils/I18n";
+
+/**
+ * Minimal structural contract for accessing the hosting GeneratorHost without importing
+ * it directly (which would create a circular dependency between WizardLayout ↔ GeneratorHost).
+ */
+interface IWizardCapableHost {
+    /** Returns the active StateManager. Used to extract a payload snapshot at step-change time. */
+    getStateManager(): { extractPayload(): unknown } | null;
+    /** Fires a UI5 event upward on the host control. */
+    fireEvent?(eventName: string, params?: Record<string, unknown>, allowPreventDefault?: boolean): unknown;
+    /** Programmatically injects a custom validation error onto a field path. */
+    addCustomError?(fieldPath: string, message: string): void;
+    /** Programmatically clears a custom validation error from a field path. */
+    clearCustomError?(fieldPath: string): void;
+}
+
+/**
+ * Layout Manager that generates a custom paginated step navigator.
+ * Renders exactly one step at a time, validates current-step fields before advancing,
+ * and fires `beforeLayoutSectionChange` with a full async API before each step transition.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.layouts
+ * @internal
+ */
+export class WizardLayout implements ILayoutManager {
+    /**
+     * Renders the wizard as a custom step-by-step navigator.
+     *
+     * @param schema The active JSON schema object containing `uiLayout` step groups.
+     * @param modelName The bound UI5 model name for data bindings.
+     * @param engine The central Engine orchestrator for field generation and validation.
+     * @param onSubmit Hook executed when the user completes the final step successfully.
+     * @returns {Control} A VBox root container comprising the step header, content, and navigation.
+     */
+    public render(schema: ISchema, modelName: string, engine: Engine, onSubmit?: () => void): Control {
+        if (!schema.uiLayout || !Array.isArray(schema.uiLayout)) {
+            Logger.warn(
+                "[MetaUI WizardLayout] Missing 'uiLayout' array in schema. Cannot build step navigator.",
+                "",
+                "WizardLayout"
+            );
+            return new VBox();
+        }
+
+        const stepElements: ILayoutElement[] = [];
+        let pendingLooseElements: ILayoutElement[] = [];
+        for (const el of schema.uiLayout) {
+            if (el.type === "Group" || el.type === "WizardStep") {
+                if (pendingLooseElements.length > 0) {
+                    stepElements.push({
+                        type: "WizardStep",
+                        label: schema.title || I18n.getText(TEXT_KEY.wizardStepTitle, [stepElements.length + 1]),
+                        elements: pendingLooseElements
+                    });
+                    pendingLooseElements = [];
+                }
+                stepElements.push(el);
+            } else {
+                pendingLooseElements.push(el);
+            }
+        }
+        if (pendingLooseElements.length > 0) {
+            stepElements.push({
+                type: "WizardStep",
+                label: schema.title || I18n.getText(TEXT_KEY.wizardStepTitle, [stepElements.length + 1]),
+                elements: pendingLooseElements
+            });
+        }
+        if (stepElements.length === 0) {
+            Logger.warn("[MetaUI WizardLayout] No Group or WizardStep elements found in uiLayout.", "", "WizardLayout");
+            return new VBox();
+        }
+
+        const totalSteps = stepElements.length;
+        const stepForms: SimpleForm[] = [];
+        const stepFieldPaths: string[][] = [];
+
+        stepElements.forEach((element: ILayoutElement) => {
+            const fieldPaths: string[] = [];
+            stepForms.push(WizardStepRenderer.buildStepForm(element, schema, modelName, engine, fieldPaths));
+            stepFieldPaths.push(fieldPaths);
+        });
+
+        let currentStepIndex = 0;
+        let navigationEpoch = 0;
+
+        const stepTitleControl = new MTitle({ level: TitleLevel.H3 });
+        const stepCounterLabel = new Text();
+        const progressBar = new ProgressIndicator({
+            showValue: false,
+            state: ValueState.None,
+            height: "0.5rem"
+        }).addStyleClass("sapUiTinyMarginTop");
+        // A bare role="progressbar" announces "50%" and nothing else. The counter beside it already says
+        // "Step 2 of 4" on screen, so it names the bar rather than a second copy of the same sentence.
+        AccessibilityUtil.associateAriaLabel(progressBar, stepCounterLabel);
+
+        const contentArea = new VBox({ width: "100%" });
+        // Each step's form is a region in its own right. Naming it with the live step title is what makes a
+        // screen reader announce "Delivery details, form" on entry instead of dropping the user into a run
+        // of unrelated fields with no indication of which step they belong to.
+        stepForms.forEach((stepForm) => {
+            AccessibilityUtil.associateAriaLabel(stepForm, stepTitleControl);
+            contentArea.addDependent(stepForm);
+        });
+
+        const sectionChangeErrorPaths: Set<string> = new Set();
+        const clearSectionChangeErrors = (): void => {
+            if (sectionChangeErrorPaths.size === 0) {
+                return;
+            }
+            const hostRef: IWizardCapableHost | undefined = engine.host;
+            for (const errPath of Array.from(sectionChangeErrorPaths)) {
+                if (hostRef && typeof hostRef.clearCustomError === "function") {
+                    hostRef.clearCustomError(errPath);
+                } else {
+                    engine.reportCustomError(errPath, null);
+                    const plugin: IPlugin | undefined = engine.getPluginByPath(errPath);
+                    if (plugin) {
+                        plugin.setVisualValidationState(true);
+                    }
+                }
+            }
+            sectionChangeErrorPaths.clear();
+        };
+
+        const prevButton = new Button({
+            text: I18n.getText(TEXT_KEY.wizardPrevious),
+            icon: "sap-icon://navigation-left-arrow",
+            enabled: false,
+            press: () => {
+                navigationEpoch++;
+                clearSectionChangeErrors();
+                navigateTo(currentStepIndex - 1);
+            }
+        });
+
+        const nextButton = new Button({
+            type: ButtonType.Emphasized,
+            text: I18n.getText(totalSteps === 1 ? TEXT_KEY.wizardComplete : TEXT_KEY.wizardNextStep),
+            icon: "sap-icon://navigation-right-arrow",
+            iconFirst: false,
+            press: () => handleNextPress()
+        });
+
+        const navigateTo = (index: number): void => {
+            if (index < 0 || index >= totalSteps) {
+                Logger.error(`Invalid navigation target: step ${index}`, undefined, "WizardLayout");
+                return;
+            }
+            currentStepIndex = index;
+            const element = stepElements[currentStepIndex];
+            const isLastStep = currentStepIndex === totalSteps - 1;
+
+            stepTitleControl.setText(
+                element.label || I18n.getText(TEXT_KEY.wizardStepTitle, [currentStepIndex + 1])
+            );
+            stepCounterLabel.setText(
+                I18n.getText(TEXT_KEY.wizardStepCounter, [currentStepIndex + 1, totalSteps])
+            );
+            progressBar.setPercentValue(((currentStepIndex + 1) / totalSteps) * 100);
+
+            const removedItems = contentArea.removeAllItems();
+            for (const removed of removedItems) {
+                contentArea.addDependent(removed);
+            }
+            contentArea.addItem(stepForms[currentStepIndex]);
+
+            prevButton.setEnabled(currentStepIndex > 0);
+            nextButton.setText(I18n.getText(isLastStep ? TEXT_KEY.wizardComplete : TEXT_KEY.wizardNextStep));
+            nextButton.setIcon(isLastStep ? "sap-icon://accept" : "sap-icon://navigation-right-arrow");
+        };
+
+        const handleNextPress = (): void => {
+            const pressEpoch = ++navigationEpoch;
+            const originStepIndex = currentStepIndex;
+            const targetStepIndex = originStepIndex + 1;
+            clearSectionChangeErrors();
+            if (!WizardStepRenderer.validateStep(stepFieldPaths[originStepIndex], engine, schema)) {
+                Logger.debug(`Step ${originStepIndex} failed local validation. Blocking navigation.`, undefined, "WizardLayout");
+                return;
+            }
+
+            if (originStepIndex === totalSteps - 1) {
+                if (onSubmit) {
+                    onSubmit();
+                }
+                return;
+            }
+
+            const host: IWizardCapableHost | undefined = engine.host;
+            if (!host || typeof host.fireEvent !== "function") {
+                navigateTo(targetStepIndex);
+                return;
+            }
+
+            const sm = host.getStateManager();
+            const payload: unknown = sm ? sm.extractPayload() : {};
+            let isPrevented = false;
+            let hasHardError = false;
+            let isNavigated = false;
+            let inEventDispatch = true;
+            let resumeRequestedSync = false;
+
+            const advance = (): void => {
+                if (
+                    !isNavigated &&
+                    !hasHardError &&
+                    navigationEpoch === pressEpoch &&
+                    currentStepIndex === originStepIndex
+                ) {
+                    isNavigated = true;
+                    navigateTo(targetStepIndex);
+                }
+            };
+
+            const allowed = host.fireEvent(
+                "beforeLayoutSectionChange",
+                {
+                    stepIndex: originStepIndex,
+                    currentSectionIndex: originStepIndex,
+                    newSectionIndex: targetStepIndex,
+                    payload,
+                    preventDefault: () => {
+                        isPrevented = true;
+                        resumeRequestedSync = false;
+                    },
+                    addError: (fieldPath: string, errorMessage: string) => {
+                        isPrevented = true;
+                        hasHardError = true;
+                        resumeRequestedSync = false;
+                        const normalizedPath = fieldPath.startsWith("/") ? fieldPath : `/${fieldPath}`;
+                        sectionChangeErrorPaths.add(normalizedPath);
+                        if (typeof host.addCustomError === "function") {
+                            host.addCustomError(normalizedPath, errorMessage);
+                        } else {
+                            engine.reportCustomError(normalizedPath, errorMessage);
+                            const plugin: IPlugin | undefined = engine.getPluginByPath(normalizedPath);
+                            if (plugin) {
+                                plugin.setVisualValidationState(false, errorMessage);
+                            }
+                        }
+                    },
+                    resumeNavigation: () => {
+                        if (inEventDispatch) {
+                            if (!hasHardError) {
+                                resumeRequestedSync = true;
+                            }
+                        } else {
+                            advance();
+                        }
+                    }
+                },
+                true
+            );
+
+            inEventDispatch = false;
+            if (allowed === false) {
+                isPrevented = true;
+                resumeRequestedSync = false;
+            }
+            if ((!isPrevented || resumeRequestedSync) && !hasHardError) {
+                advance();
+            }
+        };
+
+        navigateTo(0);
+
+        const navBar = new HBox({
+            width: "100%",
+            justifyContent: FlexJustifyContent.SpaceBetween,
+            alignItems: FlexAlignItems.Center,
+            items: [prevButton, nextButton]
+        }).addStyleClass("sapUiSmallMarginTop");
+
+        const header = new VBox({
+            width: "100%",
+            items: [
+                new HBox({
+                    justifyContent: FlexJustifyContent.SpaceBetween,
+                    alignItems: FlexAlignItems.Center,
+                    width: "100%",
+                    items: [stepTitleControl, stepCounterLabel]
+                }),
+                progressBar
+            ]
+        }).addStyleClass("sapUiSmallMarginBottom");
+
+        return new VBox({
+            width: "100%",
+            items: [header, contentArea, navBar]
+        });
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/layouts/WizardStepRenderer.ts

@@ -0,0 +1,112 @@
+/**
+ * @file WizardStepRenderer.ts
+ * @description Renders individual wizard step SimpleForm containers and validates per-step field paths.
+ */
+
+import SimpleForm from "sap/ui/layout/form/SimpleForm";
+import { ISchema, ILayoutElement } from "../interfaces/ISchema";
+import { Engine } from "../core/Engine";
+import { PayloadValidator } from "../core/PayloadValidator";
+import { SchemaNormalizer } from "../core/SchemaNormalizer";
+import { LayoutElementWalker, LayoutFieldFactory } from "./LayoutElementWalker";
+
+/**
+ * Stateless helper for building and validating individual wizard steps in `WizardLayout`.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.layouts
+ * @internal
+ */
+export class WizardStepRenderer {
+    /**
+     * Validates all fields registered during a specific step's form build.
+     * Routes error painting through `engine.reportSchemaError()` so both default and
+     * `useMessageManager` modes are updated consistently.
+     *
+     * @param fieldPaths The list of binding paths collected during the step's form build.
+     * @param engine The Engine instance that holds the plugin registry and validation ledger.
+     * @param schema Optional root schema for resolving array/table sub-layouts.
+     * @returns {boolean} True if all fields are valid, false if any failed.
+     */
+    public static validateStep(fieldPaths: string[], engine: Engine, schema?: ISchema): boolean {
+        engine.host?.evaluatePoliciesNow?.();
+        let allValid = true;
+        const activeModel = engine.getModel() as { getProperty?: (p: string) => unknown } | undefined;
+
+        for (const path of fieldPaths) {
+            const plugin = engine.getPluginByPath(path);
+            if (plugin) {
+                if (engine.isInsideAbsentOptionalObject(path)) {
+                    engine.reportSchemaError(path, null);
+                    continue;
+                }
+                const result = plugin.validate();
+                if (!result.isValid) {
+                    engine.reportSchemaError(path, result.errorMessage || "This field is required.");
+                    allValid = false;
+                } else {
+                    engine.reportSchemaError(path, null);
+                }
+            } else if (schema) {
+                const scopeStr = `#/properties/${path.replace(/^\//, "").replace(/\//g, "/properties/")}`;
+                const { meta } = SchemaNormalizer.resolveScope(schema, scopeStr);
+                if (meta && meta.ui?.visible !== false) {
+                    if (meta.type === "array") {
+                        if (!engine.validateArrayPath(path, meta)) {
+                            allValid = false;
+                        }
+                    } else {
+                        const val = activeModel?.getProperty ? activeModel.getProperty(path) : undefined;
+                        const res = PayloadValidator.validateTree(
+                            meta,
+                            val,
+                            (ref) => engine.host?.getSchemaDefinition?.(ref) ?? null
+                        );
+                        if (!res.isValid) {
+                            engine.reportSchemaError(path, res.errorMessage || "Invalid field.");
+                            allValid = false;
+                        } else {
+                            engine.reportSchemaError(path, null);
+                        }
+                    }
+                }
+            }
+        }
+        if (engine.hasActiveErrorsForPaths(fieldPaths)) {
+            allValid = false;
+        }
+        return allValid;
+    }
+
+    /**
+     * Constructs a `SimpleForm` for a single wizard step, recursively rendering all
+     * child layout elements and collecting their binding paths into `fieldPaths`.
+     *
+     * @param stepElement The top-level Group/WizardStep layout element for this step.
+     * @param schema The active JSON schema.
+     * @param modelName The UI5 JSONModel alias for data binding.
+     * @param engine The Engine instance for field generation.
+     * @param fieldPaths Collector array — all binding paths generated for this step are pushed here.
+     * @returns {SimpleForm} The assembled `SimpleForm` for this wizard step.
+     */
+    public static buildStepForm(
+        stepElement: ILayoutElement,
+        schema: ISchema,
+        modelName: string,
+        engine: Engine,
+        fieldPaths: string[]
+    ): SimpleForm {
+        const form = LayoutFieldFactory.createSimpleForm(undefined, schema.ui);
+
+        if (stepElement.elements && Array.isArray(stepElement.elements)) {
+            LayoutElementWalker.walk(
+                stepElement.elements,
+                schema,
+                engine,
+                LayoutElementWalker.createSimpleFormSink(form, schema, modelName, engine, "WizardLayout", fieldPaths),
+                "WizardLayout"
+            );
+        }
+
+        return form;
+    }
+}