@siliconst/metaui 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# 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!*

package/package.json

@@ -0,0 +1,35 @@
+{
+  "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"
+    ]
+  }
+}

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

@@ -0,0 +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>

package/src/nz/co/siliconst/ui5/metaui/controls/GeneratorHost.ts

@@ -0,0 +1,162 @@
+/**
+ * @file GeneratorHost.ts
+ * @description The core UI5 custom control that exposes the MetaUI engine to host applications.
+ */
+
+import Control from "sap/ui/core/Control";
+import RenderManager from "sap/ui/core/RenderManager";
+import Dialog from "sap/m/Dialog";
+import Button from "sap/m/Button";
+import { SchemaNormalizer } from "../core/SchemaNormalizer";
+import { Engine } from "../core/Engine";
+import { StateManager } from "../core/StateManager";
+import { BaseLayout } from "../layouts/BaseLayout";
+
+/**
+ * Enterprise wrapper element for embedding or popping the dynamic form.
+ * 
+ * @namespace nz.co.siliconst.ui5.metaui.controls
+ */
+export default class GeneratorHost extends Control {
+    
+    private stateManager: StateManager | null = null;
+    private generatedContent: Control | null = null;
+
+    static readonly metadata = {
+        properties: {
+            /** The raw JSON metadata schema provided by the ABAP backend. */
+            schemaDefinition: { type: "object", defaultValue: null },
+            /** The initial data payload to populate the fields. */
+            initialData: { type: "object", defaultValue: {} }
+        },
+        aggregations: {
+            /** The internal hidden container holding the generated layouts. */
+            _content: { type: "sap.ui.core.Control", multiple: false, visibility: "hidden" }
+        },
+        events: {
+            /** 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" }
+                }
+            },
+            /** Triggered if the dialog is cancelled. */
+            cancel: {}
+        }
+    };
+
+    /**
+     * Standard UI5 control renderer. Renders the generated internal content.
+     */
+    static renderer = {
+        apiVersion: 2,
+        render(rm: RenderManager, control: GeneratorHost) {
+            rm.openStart("div", control);
+            rm.style("width", "100%");
+            rm.style("height", "100%");
+            rm.openEnd();
+            
+            const content = control.getAggregation("_content") as Control;
+            if (content) {
+                rm.renderControl(content);
+            }
+            
+            rm.close("div");
+        }
+    };
+
+    /**
+     * Initializes the UI5 control.
+     */
+    public init(): void {
+        super.init();
+    }
+
+    /**
+     * Lifecycle hook to automatically generate the layout if bound declaratively in XML.
+     */
+    public onBeforeRendering(): void {
+        if (!this.generatedContent && this.getProperty("schemaDefinition")) {
+            this.generate();
+        }
+    }
+
+    /**
+     * Extracts the payload and fires the submit event manually. Useful for inline XML embedding.
+     */
+    public triggerSubmit(): void {
+        if (this.stateManager) {
+            const payload = this.stateManager.extractPayload();
+            this.fireEvent("submit", { payload });
+        }
+    }
+
+    /**
+     * Triggers the engine to parse the schema and build the layout.
+     * Must be called manually or hooked into onBeforeRendering if properties are bound.
+     */
+    public generate(): void {
+        const rawSchema = this.getProperty("schemaDefinition");
+        const initialData = this.getProperty("initialData");
+
+        if (!rawSchema) {
+            throw new Error("[MetaUI] Cannot generate layout without a schemaDefinition.");
+        }
+
+        // 1. Normalize schema
+        const normalizedSchema = SchemaNormalizer.normalize(rawSchema);
+
+        // 2. Bootstrap isolated State Manager
+        this.stateManager = new StateManager(initialData);
+        this.setModel(this.stateManager.getModel(), "meta");
+
+        // 3. Delegate to Layout Engine
+        const engine = new Engine();
+        const layoutFactory = new BaseLayout();
+        
+        this.generatedContent = engine.build(normalizedSchema, layoutFactory);
+
+        // 4. Mount into hidden aggregation
+        this.setAggregation("_content", this.generatedContent);
+    }
+
+    /**
+     * Dialog Modality: Opens the generated layout inside a sap.m.Dialog.
+     * Automatically wires up 'Save' and 'Cancel' buttons.
+     */
+    public openInDialog(title: string = "Dynamic Form", submitButtonText: string = "Save"): void {
+        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: () => {
+                    if (this.stateManager) {
+                        const payload = this.stateManager.extractPayload();
+                        this.fireEvent("submit", { payload });
+                    }
+                    dialog.close();
+                }
+            }),
+            endButton: new Button({
+                text: "Cancel",
+                press: () => {
+                    this.fireEvent("cancel");
+                    dialog.close();
+                }
+            }),
+            afterClose: () => {
+                dialog.destroy();
+            }
+        });
+
+        dialog.open();
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/core/ConditionEngine.ts

@@ -0,0 +1,40 @@
+/**
+ * @file ConditionEngine.ts
+ * @description Evaluates dynamic rules to alter the schema in real-time.
+ */
+
+import { EventBus } from "./EventBus";
+import { ISchema } from "../interfaces/ISchema";
+import { IFieldChangeEvent } from "../interfaces/IEventBus";
+
+/**
+ * Engine that listens to the EventBus and evaluates cross-field dependencies.
+ */
+export class ConditionEngine {
+    private schema: ISchema;
+
+    /**
+     * Initializes the ConditionEngine with the active schema.
+     * @param schema The current UI layout schema.
+     */
+    constructor(schema: ISchema) {
+        this.schema = schema;
+        this.initializeListeners();
+    }
+
+    /**
+     * Subscribes to the EventBus for real-time field change interception.
+     */
+    private initializeListeners(): void {
+        EventBus.getInstance().subscribe(this.handleEvent.bind(this));
+    }
+
+    /**
+     * Internal handler to evaluate business rules when a field is updated.
+     * @param event The structured change event.
+     */
+    private handleEvent(event: IFieldChangeEvent): void {
+        // Architecture hook: Logic to evaluate conditions against the schema 
+        // and update plugin properties will be injected here in later phases.
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/core/Engine.ts

@@ -0,0 +1,56 @@
+/**
+ * @file Engine.ts
+ * @description The central orchestrator that routes data between the Layout Factory and Plugin Registry.
+ */
+
+import { ISchema } from "../interfaces/ISchema";
+import { ILayoutManager } from "../interfaces/ILayoutManager";
+import { ConditionEngine } from "./ConditionEngine";
+import Control from "sap/ui/core/Control";
+import VBox from "sap/m/VBox";
+
+/**
+ * The MetaUI Engine. Responsible for bootstrapping the layout generation.
+ * Follows strict Orchestrator patterns; delegates all actual rendering to LayoutManagers.
+ */
+export class Engine {
+    private conditionEngine: ConditionEngine | null = null;
+    
+    /**
+     * Evaluates the schema and delegates generation to the layout factory.
+     * @param schema The fully normalized schema definition.
+     * @param layoutManager The injected layout factory class.
+     * @returns The populated UI5 layout container.
+     */
+    public build(schema: ISchema, layoutManager: ILayoutManager): Control {
+        // Bootstrap the condition engine to start listening for field events in this schema
+        this.conditionEngine = new ConditionEngine(schema);
+        
+        if (schema.mode === "form") {
+            return layoutManager.renderForm(schema);
+        } else if (schema.mode === "table") {
+            if (!schema.tables || schema.tables.length === 0) {
+                throw new Error("[MetaUI] Table mode requires at least one table definition.");
+            }
+            return layoutManager.renderTable(schema.tables[0]);
+        } else if (schema.mode === "mixed") {
+            const container = new VBox({ renderType: "Bare" });
+            
+            // 1. Render the top-level form if there are root fields
+            if (schema.rootFields && schema.rootFields.length > 0) {
+                container.addItem(layoutManager.renderForm(schema));
+            }
+            
+            // 2. Render all tables sequentially below the form
+            if (schema.tables && schema.tables.length > 0) {
+                schema.tables.forEach(tableMeta => {
+                    container.addItem(layoutManager.renderTable(tableMeta));
+                });
+            }
+            
+            return container;
+        }
+        
+        throw new Error(`[MetaUI] Mode '${schema.mode}' is not yet implemented or invalid.`);
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/core/EventBus.ts

@@ -0,0 +1,45 @@
+/**
+ * @file EventBus.ts
+ * @description Internal pub/sub channel for managing cross-field dependencies.
+ */
+
+import { IEventBus, IFieldChangeEvent } from "../interfaces/IEventBus";
+
+/**
+ * Singleton orchestrator for localized state changes across the generated UI layout.
+ */
+export class EventBus implements IEventBus {
+    private static instance: EventBus;
+    private listeners: Array<(event: IFieldChangeEvent) => void> = [];
+
+    private constructor() {
+        // Enforce singleton
+    }
+
+    /**
+     * Retrieves the singular instance of the EventBus.
+     * @returns The EventBus singleton.
+     */
+    public static getInstance(): EventBus {
+        if (!EventBus.instance) {
+            EventBus.instance = new EventBus();
+        }
+        return EventBus.instance;
+    }
+
+    /**
+     * Publishes a value change event to all internal subscribers.
+     * @param event The structured payload of the field change.
+     */
+    public publishFieldChange(event: IFieldChangeEvent): void {
+        this.listeners.forEach(listener => listener(event));
+    }
+
+    /**
+     * Registers a callback listener to react to field changes.
+     * @param listener The callback function.
+     */
+    public subscribe(listener: (event: IFieldChangeEvent) => void): void {
+        this.listeners.push(listener);
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/core/PluginRegistry.ts

@@ -0,0 +1,56 @@
+/**
+ * @file PluginRegistry.ts
+ * @description Centralized hub for mapping UI5 controls to SAP schema data types.
+ * Enforces the Registry Pattern to decouple the core engine from specific UI5 control implementations.
+ */
+
+import { IPlugin } from "../interfaces/IPlugin";
+import { FieldType } from "../interfaces/ISchema";
+
+/**
+ * Singleton registry that manages the lifecycle and lookup of UI5 plugin constructors.
+ */
+export class PluginRegistry {
+    private static instance: PluginRegistry;
+    
+    /** Internal map linking string types to their respective constructor functions. */
+    private plugins: Map<FieldType, new () => IPlugin> = new Map();
+
+    private constructor() {
+        // Enforce singleton
+    }
+
+    /**
+     * Retrieves the singular instance of the PluginRegistry.
+     * @returns The PluginRegistry singleton.
+     */
+    public static getInstance(): PluginRegistry {
+        if (!PluginRegistry.instance) {
+            PluginRegistry.instance = new PluginRegistry();
+        }
+        return PluginRegistry.instance;
+    }
+
+    /**
+     * Registers a new UI control plugin against a specific schema primitive type.
+     * @param type The primitive FieldType (e.g., 'string', 'date').
+     * @param pluginConstructor The class constructor for the plugin.
+     */
+    public register(type: FieldType, pluginConstructor: new () => IPlugin): void {
+        this.plugins.set(type, pluginConstructor);
+    }
+
+    /**
+     * Instantiates and returns a new plugin based on the requested primitive type.
+     * @param type The primitive FieldType to look up.
+     * @throws Error if no plugin has been registered for the provided type.
+     * @returns A newly instantiated plugin ready for rendering.
+     */
+    public getPlugin(type: FieldType): IPlugin {
+        const PluginClass = this.plugins.get(type);
+        if (!PluginClass) {
+            throw new Error(`[MetaUI] No plugin registered for FieldType: ${type}`);
+        }
+        return new PluginClass();
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/core/SchemaNormalizer.ts

@@ -0,0 +1,31 @@
+/**
+ * @file SchemaNormalizer.ts
+ * @description Transforms and validates incoming JSON payloads into the strict ISchema matrix.
+ */
+
+import { ISchema } from "../interfaces/ISchema";
+
+/**
+ * Utility class ensuring data fidelity before layout construction begins.
+ */
+export class SchemaNormalizer {
+    
+    /**
+     * Validates that the provided raw payload conforms to the required ISchema structures.
+     * @param rawSchema The heterogeneous JSON object provided to the Engine.
+     * @returns The strictly cast ISchema matrix.
+     * @throws Error if the mandatory schema properties are missing.
+     */
+    public static normalize(rawSchema: any): ISchema {
+        if (!rawSchema || typeof rawSchema !== 'object') {
+            throw new Error("[MetaUI] Invalid Schema Payload: Payload is not an object.");
+        }
+        
+        if (!rawSchema.mode || !rawSchema.rootFields || !rawSchema.tables) {
+            throw new Error("[MetaUI] Invalid Schema Payload: Missing required structures (mode, rootFields, tables).");
+        }
+
+        // Return the strongly typed and validated schema block.
+        return rawSchema as ISchema;
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/core/StateManager.ts

@@ -0,0 +1,56 @@
+/**
+ * @file StateManager.ts
+ * @description Isolated internal state management. Decouples the MetaUI engine from external host models.
+ */
+
+import JSONModel from "sap/ui/model/json/JSONModel";
+import ManagedObject from "sap/ui/base/ManagedObject";
+
+/**
+ * Manages the isolated internal data payload for the MetaUI engine.
+ */
+export class StateManager {
+    private model: JSONModel;
+
+    /**
+     * Initializes the state manager with an optional initial payload.
+     * @param initialData The initial JSON payload to populate the fields.
+     */
+    constructor(initialData: Record<string, any> = {}) {
+        // Deep copy to ensure no reference leakage from the host application
+        const safeData = JSON.parse(JSON.stringify(initialData));
+        this.model = new JSONModel(safeData);
+        this.model.setDefaultBindingMode("TwoWay");
+    }
+
+    /**
+     * Retrieves the isolated JSONModel instance to attach to the root GeneratorHost control.
+     * @returns The internal JSONModel.
+     */
+    public getModel(): JSONModel {
+        return this.model;
+    }
+
+    /**
+     * Binds a generated UI control property to a path in the internal model.
+     * @param control The target UI5 Control.
+     * @param property The UI5 property name (e.g., 'value').
+     * @param bindingPath The exact path in the JSON payload.
+     */
+    public bindControl(control: ManagedObject, property: string, bindingPath: string): void {
+        control.bindProperty(property, {
+            path: bindingPath,
+            model: "meta" // Assumes the model is bound to the root container with the name 'meta'
+        });
+    }
+
+    /**
+     * Extracts the flat JavaScript object representing the current state of the UI.
+     * @returns A serialized record of the data payload, free of UI5 wrappers.
+     */
+    public extractPayload(): Record<string, any> {
+        // Create a deep copy to prevent accidental mutations by the host
+        const data = this.model.getData();
+        return JSON.parse(JSON.stringify(data));
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/interfaces/IEventBus.ts

@@ -0,0 +1,29 @@
+/**
+ * @file IEventBus.ts
+ * @description Pub/Sub interface for localized cross-field communication and state logic.
+ */
+
+/**
+ * Describes a state change payload fired by a plugin.
+ */
+export interface IFieldChangeEvent {
+    fieldName: string;
+    newValue: any;
+}
+
+/**
+ * Contract for the internal event orchestrator to manage conditional UI logic.
+ */
+export interface IEventBus {
+    /**
+     * Publishes a value change event to the internal channel.
+     * @param event The structured event detailing which field changed and its new value.
+     */
+    publishFieldChange(event: IFieldChangeEvent): void;
+
+    /**
+     * Subscribes a listener to react to field value changes.
+     * @param listener The callback function to execute when a change occurs.
+     */
+    subscribe(listener: (event: IFieldChangeEvent) => void): void;
+}

package/src/nz/co/siliconst/ui5/metaui/interfaces/ILayoutManager.ts

@@ -0,0 +1,26 @@
+/**
+ * @file ILayoutManager.ts
+ * @description Factory contract for generating UI5 layout containers (Forms/Tables).
+ */
+
+import Control from "sap/ui/core/Control";
+import { ISchema, ITableMetadata } from "./ISchema";
+
+/**
+ * The factory interface responsible for structuring the visual grid.
+ */
+export interface ILayoutManager {
+    /**
+     * Constructs a responsive form layout container utilizing native UI5 grids.
+     * @param schema The master schema containing rootFields to be mounted.
+     * @returns A populated UI5 container (e.g., sap.ui.layout.form.SimpleForm).
+     */
+    renderForm(schema: ISchema): Control;
+
+    /**
+     * Constructs an analytical or responsive table layout.
+     * @param tableMeta The metadata defining the table columns.
+     * @returns A UI5 Table control (e.g., sap.m.Table or sap.ui.table.Table).
+     */
+    renderTable(tableMeta: ITableMetadata): Control;
+}