@siliconst/metaui 1.0.0 → 1.2.0

package/README.md

@@ -1,123 +1,134 @@
-# MetaUI - Dynamic SAP UI5 Rendering Engine
-
-MetaUI is an UI5 library that dynamically generates fully accessible, Fiori-compliant forms and tables purely from JSON schemas. It utilizes an **Isolated State Pattern** to entirely decouple from host OData bindings, yielding a clean JSON payload upon submission.
-
-## 🏗️ Architecture
-1. **Standard UI5**: Relies strictly on native UI5 layout grids (`sap.ui.layout.form.SimpleForm`, `sap.m.Table`).
-2. **Schema Normalization**: Ingests ABAP RTTI JSON payloads and normalizes them into a strict `ISchema` layout matrix.
-3. **Plugin Registry**: Maps primitive schema types (`string`, `number`, `boolean`, `dropdown`, `date`) directly to discrete UI5 control plugins (`sap.m.Input`, `sap.m.StepInput`, etc.).
-
-## 📚 Documentation Wiki
-Full payload references and API details are tracked in Git under the `docs/` folder:
-*   [Payload Formats & Schema API](docs/payload_formats.md)
-
-## 🚀 How to Test the Sandbox
-
-To understand how the engine works, a standalone test sandbox has been provided. It asynchronously loads two physical files:
-*   `test/mockSchema.json` - The schema definition detailing field types, required states, and dropdown arrays.
-*   `test/mockData.json` - The initial state payload to populate the form.
-
-### Running the Test
-You **cannot** run this test by double-clicking the `index.html` file due to browser CORS restrictions blocking `fetch()`. You must run it via a local web server.
-
-1. Open a terminal in the root `MetaUI` project folder.
-2. Run a static file server using Node.js:
-   ```bash
-   npx serve -p 8080 .
-   ```
-3. Open your web browser and navigate to:
-   `http://localhost:8080/test/index.html`
-4. Click **"Open MetaUI Dialog"**.
-5. Modify the values in the form. Notice the built-in validation rules (e.g., required fields, dropdown selections).
-6. Click **Save**. The clean, extracted JSON payload will be printed directly to the text area.
-
-## 📦 Installation (NPM)
-
-If you are developing a modern UI5 application utilizing `ui5-tooling`, you can pull this engine in directly via NPM (once published to your internal registry):
-
-```bash
-npm install @siliconst/ui5-metaui
-```
-
-### 1. ui5.yaml Configuration
-Ensure your application consumes the library by adding it to your `ui5.yaml` dependencies:
-
-```yaml
-specVersion: "3.0"
-metadata:
-  name: my.custom.app
-type: application
-builder:
-  customTasks:
-    - name: ui5-tooling-transpile-task
-      afterTask: replaceVersion
----
-specVersion: "3.0"
-kind: extension
-type: project-shim
-metadata:
-  name: my.custom.app.shim
-shims:
-  configurations:
-    "@siliconst/ui5-metaui":
-      type: library
-```
-
-### 2. manifest.json Registration
-You must explicitly declare the library dependency in your application's `manifest.json` so the UI5 core automatically downloads the runtime files and triggers the internal `PluginRegistry` bootstrapper.
-
-```json
-"sap.ui5": {
-  "dependencies": {
-    "minUI5Version": "1.120.0",
-    "libs": {
-      "sap.m": {},
-      "sap.ui.core": {},
-      "nz.co.siliconst.ui5.metaui": {}
-    }
-  }
-}
-```
-
-## 💻 Instantiating the Engine in your Controller
-
-Once installed and registered, simply require the `GeneratorHost` control in your view controllers:
-
-```javascript
-sap.ui.define([
-    "sap/ui/core/mvc/Controller",
-    "nz/co/siliconst/ui5/metaui/controls/GeneratorHost"
-], function(Controller, GeneratorHost) {
-    return Controller.extend("my.app.controller.Main", {
-        
-        openDynamicForm: function(schemaPayload, dataPayload) {
-            const host = new GeneratorHost({
-                schemaDefinition: schemaPayload, // The RTTI schema from ABAP
-                initialData: dataPayload,        // Your isolated JSON payload
-                submit: (oEvent) => {
-                    const finalJsonPayload = oEvent.getParameter("payload");
-                    // Send finalJsonPayload back to SAP ABAP via your REST/OData API!
-                }
-            });
-            
-            host.openInDialog("Edit Customer");
-        }
-    });
-});
-```
-
-## 🔗 Declarative XML Model Binding
-Because `GeneratorHost` extends `sap.ui.core.Control`, you can also embed it directly into your XML Views and bind standard UI5 Models (JSON, OData) natively to its properties.
-
-First, add the namespace to your XML View:
-```xml
-xmlns:meta="nz.co.siliconst.ui5.metaui.controls"
-```
-
-Then bind your host application's models directly to the control:
-```xml
-<meta:GeneratorHost 
-    schemaDefinition="{schemaModel>/CustomerSchema}" 
-    initialData="{odataModel>/Customers('1001')}" />
-```
-*Note: The engine will safely clone the incoming `initialData` into its own isolated state, preventing any unwanted two-way binding bleed into your host OData models until you explicitly catch the `submit` event!*
+# MetaUI
+
+**MetaUI** is a metadata-driven UI5 rendering engine. It provides a mechanism to generate SAP Fiori architectures at runtime by parsing standard JSON Schema definitions, reducing the requirement for manual XML View construction.
+
+Built for strict UI5 architecture adherence, MetaUI enforces modularity through a Plugin-based design and explicitly avoids inline DOM manipulation.
+
+✨ **[Play with the Live Interactive Demo Here!](https://SiliconStreetDev1.github.io/MetaUI/index.html)** ✨
+
+---
+
+## 🏗 Architecture & Design Tenets
+
+1. **JSON-Schema Core:** MetaUI parses standard recursive JSON Schema `properties` blocks (`Record<string, IPropertyMetadata>`).
+2. **Implicit Layout Orchestration:** The `Engine` determines standard Layouts based on payload shape. Root `object` types map to `FormLayout` clusters. Root `array` types map to `TableLayout` instances. Nested arrays trigger recursive drill-down dialogs.
+3. **ConditionEngine Compilation:** Cross-context visibility rules (e.g., `"$root.status === 'DRAFT'"`) are transpiled into native UI5 Expression Bindings to utilize native reactivity.
+4. **Strict Plugin Pipeline:** The `PluginRegistry` isolates control instantiation. Core layout managers delegate to registered implementations of `IPlugin`.
+
+---
+
+## 🚀 Quick Start (Sandbox)
+
+The repository contains an internal UI5 sandbox for testing the engine's inference logic.
+
+```bash
+# Install dependencies
+npm install
+
+# Run the UI5 development server (Sandbox application)
+npm run start
+```
+The test suite will boot at `http://localhost:8080/index.html`.
+
+---
+
+## 🛠 Integration
+
+### Installation
+
+Import the compiled library namespace into your UI5 project. 
+
+```javascript
+sap.ui.require(["nz/co/siliconst/ui5/metaui/controls/GeneratorHost"], function (GeneratorHost) {
+    const host = new GeneratorHost({
+        // The Schema Definition
+        schemaDefinition: {
+            type: "object",
+            properties: {
+                Username: { type: "string", ui: { label: "User Name" } },
+                IsActive: { type: "boolean", ui: { label: "Active", widget: "switch" } }
+            }
+        },
+        // The Data Payload
+        initialData: {
+            Username: "JDoe",
+            IsActive: true
+        }
+    });
+
+    // Option A: Render inside an existing container
+    myVBox.addItem(host);
+    
+    // Option B: Mount as an isolated Dialog
+    host.openInDialog("User Configuration", "Save");
+
+    // Capture the extracted JSON payload on submit
+    host.attachSubmit(function(oEvent) {
+        const payload = oEvent.getParameter("payload");
+        console.log(payload);
+    });
+});
+```
+
+### Declarative XML Binding
+
+MetaUI supports client-side validation based on JSON Schema constraints natively.
+
+### Mandatory Fields
+Adding `"required": true` to any property in the schema will enforce input validation prior to the `submit` event being fired.
+
+### Custom Validation Exits (`beforeSubmit`)
+For business logic requiring custom checks (e.g., async validation), the `GeneratorHost` provides a `beforeSubmit` event.
+
+```javascript
+onBeforeSubmit: function(oEvent) {
+    const payload = oEvent.getParameter("payload");
+    const preventDefault = oEvent.getParameter("preventDefault");
+    const addError = oEvent.getParameter("addError");
+
+    if (payload.CustomerName === "Reserved") {
+        addError("CustomerName", "This customer name is reserved.");
+        preventDefault();
+    }
+}
+```
+
+### Fiori Message Manager Integration
+By default, validation errors are shown locally. To aggregate validation errors into the global UI5 Message Popover, enable `useMessageManager` on the `GeneratorHost`:
+
+```xml
+<meta:GeneratorHost
+    schemaDefinition="{/mySchema}"
+    useMessageManager="true"
+    beforeSubmit=".onBeforeSubmit"
+    submit=".onSubmit" />
+```
+
+## Supported Features
+
+The `GeneratorHost` fully supports declarative XML instantiation in traditional UI5 views:
+
+```xml
+<mvc:View
+    xmlns:mvc="sap.ui.core.mvc"
+    xmlns:meta="nz.co.siliconst.ui5.metaui.controls">
+    
+    <meta:GeneratorHost 
+        id="metaHost"
+        schemaDefinition="{backend>/schema}" 
+        initialData="{backend>/data}" 
+        submit=".onFormSubmit" />
+        
+</mvc:View>
+```
+
+---
+
+## 📚 Technical Documentation
+
+For detailed information regarding the JSON Schema properties, `ui.*` orchestrations, and recursive nested arrays, consult the payload formats specification:
+
+- [Payload Formats & Directives](docs/payload_formats.md)
+- [Fiori Integration Guide](docs/fiori_integration.md)
+
+

package/package.json

@@ -1,35 +1,23 @@
-{
-  "name": "@siliconst/metaui",
-  "version": "1.0.0",
-  "description": "Dynamic Metadata UI5 Engine",
-  "author": "SiliconStreetDev1",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/SiliconStreetDev1/MetaUI.git"
-  },
-  "keywords": [
-    "ui5",
-    "metadata",
-    "engine"
-  ],
-  "files": [
-    "src",
-    "ui5.yaml",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "ui5 build --clean-dest"
-  },
-  "devDependencies": {
-    "@types/openui5": "^1.120.0",
-    "@ui5/cli": "^3.0.0",
-    "typescript": "^5.3.0",
-    "ui5-tooling-transpile": "^3.2.0"
-  },
-  "ui5": {
-    "dependencies": [
-      "ui5-tooling-transpile"
-    ]
-  }
+{
+  "name": "@siliconst/metaui",
+  "version": "1.2.0",
+  "description": "Dynamic Metadata UI5 Engine",
+  "author": "SiliconStreetDev1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SiliconStreetDev1/MetaUI.git"
+  },
+  "keywords": [
+    "ui5",
+    "metadata",
+    "engine"
+  ],
+  "files": [
+    "src",
+    "test-resources",
+    "ui5.yaml",
+    "README.md"
+  ],
+  "types": "index.d.ts"
 }

package/src/nz/co/siliconst/ui5/metaui/.library

@@ -1,7 +1,7 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<library xmlns="http://www.sap.com/sap.ui.library.xsd">
-	<name>nz.co.siliconst.ui5.metaui</name>
-	<vendor>Siliconst</vendor>
-	<version>1.0.0</version>
-	<title>MetaUI Engine</title>
-</library>
+<?xml version="1.0" encoding="UTF-8" ?>
+<library xmlns="http://www.sap.com/sap.ui.library.xsd">
+	<name>nz.co.siliconst.ui5.metaui</name>
+	<vendor>Siliconst</vendor>
+	<version>1.0.0</version>
+	<title>MetaUI Engine</title>
+</library>

package/src/nz/co/siliconst/ui5/metaui/controls/GeneratorHost-dbg.js

@@ -0,0 +1,300 @@
+sap.ui.define(["sap/ui/core/Control", "sap/m/Dialog", "sap/m/Button", "sap/m/MessagePage", "sap/base/Log", "../core/SchemaNormalizer", "../core/Engine", "../core/StateManager", "../layouts/BaseLayout"], function (Control, Dialog, Button, MessagePage, Log, ___core_SchemaNormalizer, ___core_Engine, ___core_StateManager, ___layouts_BaseLayout) {
+  "use strict";
+
+  const SchemaNormalizer = ___core_SchemaNormalizer["SchemaNormalizer"];
+  const Engine = ___core_Engine["Engine"];
+  const StateManager = ___core_StateManager["StateManager"];
+  const BaseLayout = ___layouts_BaseLayout["BaseLayout"];
+  /**
+   * Wrapper element for embedding or popping the dynamic form.
+   * 
+   * @namespace nz.co.siliconst.ui5.metaui.controls
+   */
+  const GeneratorHost = Control.extend("nz.co.siliconst.ui5.metaui.controls.GeneratorHost", {
+    constructor: function constructor() {
+      Control.prototype.constructor.apply(this, arguments);
+      this.stateManager = null;
+      this.generatedContent = null;
+      this.engine = null;
+    },
+    /**
+     * Standard UI5 control renderer. Renders the generated internal content.
+     */
+    renderer: {
+      apiVersion: 2,
+      render(rm, control) {
+        rm.openStart("div", control);
+        rm.style("width", "100%");
+        rm.style("height", "100%");
+        rm.openEnd();
+        const content = control.getAggregation("_content");
+        if (content) {
+          rm.renderControl(content);
+        }
+        rm.close("div");
+      }
+    },
+    metadata: {
+      properties: {
+        /** The raw JSON metadata schema provided by the ABAP backend. */
+        schemaDefinition: {
+          type: "any",
+          defaultValue: null
+        },
+        /** The initial data payload to populate the fields as an object. */
+        initialData: {
+          type: "any",
+          defaultValue: null
+        },
+        /** The initial data payload provided as a raw JSON string. */
+        initialDataJson: {
+          type: "string",
+          defaultValue: null
+        },
+        /** The final payload data object, updated on submit. */
+        outputData: {
+          type: "object",
+          defaultValue: null
+        },
+        /** The final payload JSON string, updated on submit. */
+        outputDataJson: {
+          type: "string",
+          defaultValue: null
+        },
+        /** If true, validation errors will be pushed to the global sap.ui.core.message.MessageManager. */
+        useMessageManager: {
+          type: "boolean",
+          defaultValue: false
+        }
+      },
+      aggregations: {
+        /** The internal hidden container holding the generated layouts. */
+        _content: {
+          type: "sap.ui.core.Control",
+          multiple: false,
+          visibility: "hidden"
+        }
+      },
+      events: {
+        /** Triggered before final submission, allowing host apps to run custom validation logic and halt submission if needed. */
+        beforeSubmit: {
+          parameters: {
+            /** The clean extracted JSON payload representing the current state. */
+            payload: {
+              type: "object"
+            },
+            /** Function to add a custom validation error message for a specific field path. */
+            addError: {
+              type: "function"
+            },
+            /** Function to prevent the default submission and dialog closure. */
+            preventDefault: {
+              type: "function"
+            }
+          }
+        },
+        /** Triggered when the user submits the form via the Dialog modality. */
+        submit: {
+          parameters: {
+            /** The clean extracted JSON payload representing the current state. */
+            payload: {
+              type: "object"
+            },
+            /** The stringified final JSON payload. */
+            payloadJson: {
+              type: "string"
+            }
+          }
+        },
+        /** Triggered if the dialog is cancelled. */
+        cancel: {}
+      }
+    },
+    /**
+     * Initializes the UI5 control.
+     */
+    init: function _init() {
+      Control.prototype.init.call(this);
+    },
+    /**
+     * Standard UI5 lifecycle hook for destruction.
+     * Guaranteed to tear down isolated models and unbind global event listeners.
+     */
+    exit: function _exit() {
+      if (this.engine) {
+        this.engine.destroy();
+        this.engine = null;
+      }
+      if (this.stateManager) {
+        this.stateManager.getModel().destroy();
+        this.stateManager = null;
+      }
+      if (this.generatedContent) {
+        this.generatedContent.destroy();
+        this.generatedContent = null;
+      }
+    },
+    /**
+     * Lifecycle hook to automatically generate the layout if bound declaratively in XML.
+     */
+    onBeforeRendering: function _onBeforeRendering() {
+      if (!this.generatedContent && this.getProperty("schemaDefinition")) {
+        this.generate();
+      }
+    },
+    /**
+     * Extracts the payload, pushes it to properties, and fires the submit event manually.
+     * Returns true if submission was successful, false if validation failed or was prevented.
+     */
+    triggerSubmit: function _triggerSubmit() {
+      if (this.stateManager && this.engine) {
+        let isPrevented = false;
+        const useMessageManager = this.getProperty("useMessageManager");
+        let messageManager = null;
+        if (useMessageManager) {
+          messageManager = sap.ui.getCore().getMessageManager();
+          messageManager.removeAllMessages();
+        }
+
+        // Helper to add messages securely via async require so it isn't a hard dependency
+        const pushMessage = (path, text) => {
+          if (useMessageManager && messageManager) {
+            sap.ui.require(["sap/ui/core/message/Message"], Message => {
+              messageManager.addMessages(new Message({
+                message: text,
+                type: "Error",
+                target: `${this.stateManager?.getModel().getId()}>/${path}`,
+                processor: this.stateManager?.getModel()
+              }));
+            });
+          }
+        };
+
+        // 1. Run global schema validation
+        if (!this.engine.validateAll()) {
+          pushMessage("", "One or more fields failed schema validation. Please review the highlighted fields.");
+          return false; // Schema validation failed, inputs already turned red
+        }
+        const payload = this.stateManager.extractPayload();
+        const payloadJson = JSON.stringify(payload);
+
+        // 2. Fire beforeSubmit exit
+        this.fireEvent("beforeSubmit", {
+          payload,
+          preventDefault: () => {
+            isPrevented = true;
+          },
+          addError: (propertyPath, errorMessage) => {
+            isPrevented = true;
+            if (useMessageManager && messageManager) {
+              pushMessage(propertyPath, errorMessage);
+            } else {
+              Log.warning(`[MetaUI] Validation Error for ${propertyPath}: ${errorMessage}`, "GeneratorHost");
+            }
+          }
+        });
+        if (isPrevented) {
+          return false; // Exit validation failed or prevented submission
+        }
+
+        // Push final values to properties (updating XML bindings)
+        this.setProperty("outputData", payload, true);
+        this.setProperty("outputDataJson", payloadJson, true);
+        this.fireEvent("submit", {
+          payload,
+          payloadJson
+        });
+        return true;
+      }
+      return false;
+    },
+    /**
+     * Triggers the engine to parse the schema and build the layout.
+     * Safely wrapped in a try/catch to prevent Launchpad crashes.
+     */
+    generate: function _generate() {
+      try {
+        const rawSchema = this.getProperty("schemaDefinition");
+        let initialData = this.getProperty("initialData");
+        const initialDataJson = this.getProperty("initialDataJson");
+        if (initialDataJson) {
+          try {
+            initialData = JSON.parse(initialDataJson);
+          } catch (e) {
+            Log.error("[MetaUI] Failed to parse initialDataJson string.", e.message, "GeneratorHost");
+          }
+        } else if (typeof initialData === "string") {
+          try {
+            initialData = JSON.parse(initialData);
+          } catch (e) {
+            Log.error("[MetaUI] Failed to parse initialData string.", e.message, "GeneratorHost");
+          }
+        }
+
+        // 1. Normalize schema (allows fallback to data inference)
+        const normalizedSchema = SchemaNormalizer.normalize(rawSchema, initialData);
+
+        // 2. Bootstrap isolated State Manager
+        this.stateManager = new StateManager(initialData || {});
+
+        // Dynamically generate a 100% unique model name for isolation
+        const modelName = "metaUI_" + this.getId();
+        this.setModel(this.stateManager.getModel(), modelName);
+
+        // 3. Delegate to Layout Engine
+        this.engine = new Engine();
+        const layoutFactory = new BaseLayout();
+        this.generatedContent = this.engine.build(normalizedSchema, layoutFactory, modelName);
+
+        // 4. Mount into hidden aggregation
+        this.setAggregation("_content", this.generatedContent);
+      } catch (error) {
+        Log.error("[MetaUI] Engine failed to generate layout. Preventing Launchpad crash.", error.message, "GeneratorHost");
+        const errorPage = new MessagePage({
+          text: "UI Generation Failed",
+          description: "The dynamic schema could not be rendered. Please check the Fiori console for diagnostic logs.",
+          icon: "sap-icon://error"
+        });
+        this.setAggregation("_content", errorPage);
+      }
+    },
+    /**
+     * Dialog Modality: Opens the generated layout inside a sap.m.Dialog.
+     * Automatically wires up 'Save' and 'Cancel' buttons.
+     */
+    openInDialog: function _openInDialog(title = "Dynamic Form", submitButtonText = "Save") {
+      if (!this.generatedContent) {
+        this.generate();
+      }
+      const dialog = new Dialog({
+        title: title,
+        contentWidth: "800px",
+        content: [this],
+        // Mount self inside the dialog
+        beginButton: new Button({
+          text: submitButtonText,
+          type: "Emphasized",
+          press: () => {
+            const success = this.triggerSubmit();
+            if (success) {
+              dialog.close();
+            }
+          }
+        }),
+        endButton: new Button({
+          text: "Cancel",
+          press: () => {
+            this.fireEvent("cancel");
+            dialog.close();
+          }
+        }),
+        afterClose: () => {
+          dialog.destroy();
+        }
+      });
+      dialog.open();
+    }
+  });
+  return GeneratorHost;
+});
+//# sourceMappingURL=GeneratorHost-dbg.js.map