@siliconst/metaui 1.0.0

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

@@ -0,0 +1,33 @@
+/**
+ * @file IPlugin.ts
+ * @description Contract for all discrete UI control generation plugins.
+ * Enforces a strict lifecycle for rendering, validation, and dynamic state updates.
+ */
+
+import Control from "sap/ui/core/Control";
+import { IFieldMetadata } from "./ISchema";
+
+/**
+ * Defines the contract that every MetaUI plugin must fulfill.
+ */
+export interface IPlugin {
+    /**
+     * Instantiates and binds the appropriate UI5 control based on the field metadata.
+     * @param fieldMetadata The immutable schema configuration for this specific field.
+     * @param bindingPath The exact model path where this field's data is stored.
+     * @returns The fully constructed and bound UI5 Control ready for layout insertion.
+     */
+    render(fieldMetadata: IFieldMetadata, bindingPath: string): Control;
+
+    /**
+     * Evaluates the current state of the UI5 control against the required schema rules.
+     * @returns True if the input is valid, false otherwise. Must set ValueState natively.
+     */
+    validate(): boolean;
+
+    /**
+     * Hook triggered when a cross-field dependency requires this field to re-evaluate its state.
+     * @param newMetadata The dynamically updated schema rules for this field.
+     */
+    onStateChange(newMetadata: IFieldMetadata): void;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * @file ISchema.ts
+ * @description Defines the core structural contract for the MetaUI engine.
+ * The schema maps perfectly to the JSON payload generated by the ABAP RTTI extractor.
+ */
+
+/**
+ * Supported data primitive types that drive plugin selection.
+ */
+export type FieldType = "string" | "number" | "boolean" | "date" | "dropdown";
+
+/**
+ * Value help structure mapping SAP Key/Text pairs.
+ */
+export interface IValueHelp {
+    /** The technical key passed back to the backend. */
+    key: string;
+    /** The localized descriptive text displayed to the user. */
+    text: string;
+}
+
+/**
+ * Metadata definition for a single atomic input field.
+ */
+export interface IFieldMetadata {
+    /** The technical field name mapping to the data model property. */
+    fieldName: string;
+    /** The primitive type determining the rendering plugin. */
+    type: FieldType;
+    /** The localized label text for the UI. */
+    label: string;
+    /** Indicates if the field is a primary key (often rendered first or highlighted). */
+    isKey: boolean;
+    /** If true, the field is rendered as a non-editable display element. */
+    isReadOnly: boolean;
+    /** If true, triggers UI5 validation to ensure a value exists. */
+    isRequired: boolean;
+    /** Maximum allowed character length for string-based inputs. */
+    maxLength?: number;
+    /** The total number of significant digits for numeric inputs. */
+    precision?: number;
+    /** The number of decimal places for numeric inputs. */
+    scale?: number;
+    /** Pre-loaded static value help arrays for dropdowns. */
+    valueHelp?: IValueHelp[];
+}
+
+/**
+ * Metadata definition for a tabular structure.
+ */
+export interface ITableMetadata {
+    /** The internal ID/name of the table. */
+    tableName: string;
+    /** The localized table header label. */
+    label: string;
+    /** Array of field definitions dictating the table's columns. */
+    fields: IFieldMetadata[];
+}
+
+/**
+ * The master schema contract ingested by the Engine to build the UI5 layout.
+ */
+export interface ISchema {
+    /** Determines the root container layout strategy. */
+    mode: "form" | "table" | "mixed";
+    /** The fields to be rendered at the root level (typically form inputs). */
+    rootFields: IFieldMetadata[];
+    /** The table structures to be rendered sequentially. */
+    tables: ITableMetadata[];
+}

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

@@ -0,0 +1,34 @@
+/**
+ * @file BaseLayout.ts
+ * @description Central layout factory that delegates to specific form or table layout engines.
+ * Implements ILayoutManager.
+ */
+
+import { ILayoutManager } from "../interfaces/ILayoutManager";
+import { ISchema, ITableMetadata } from "../interfaces/ISchema";
+import Control from "sap/ui/core/Control";
+import { FormLayout } from "./FormLayout";
+import { TableLayout } from "./TableLayout";
+
+/**
+ * The core layout manager that delegates structural grid rendering based on schema configurations.
+ */
+export class BaseLayout implements ILayoutManager {
+    /**
+     * Constructs a responsive form layout container.
+     * @param schema The master schema containing rootFields to be mounted.
+     * @returns A populated UI5 container (sap.ui.layout.form.SimpleForm).
+     */
+    public renderForm(schema: ISchema): Control {
+        return FormLayout.build(schema.rootFields);
+    }
+
+    /**
+     * Constructs a responsive table layout container.
+     * @param tableMeta The metadata defining the table columns.
+     * @returns A UI5 Table control (sap.m.Table).
+     */
+    public renderTable(tableMeta: ITableMetadata): Control {
+        return TableLayout.build(tableMeta);
+    }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * @file FormLayout.ts
+ * @description Generates a fully responsive SAP Fiori Form layout (SimpleForm).
+ */
+
+import SimpleForm from "sap/ui/layout/form/SimpleForm";
+import Label from "sap/m/Label";
+import { IFieldMetadata } from "../interfaces/ISchema";
+import { PluginRegistry } from "../core/PluginRegistry";
+
+/**
+ * Utility class strictly for constructing Form layouts without custom CSS.
+ */
+export class FormLayout {
+    /**
+     * Builds a SimpleForm with ResponsiveGridLayout, injecting the requested plugins.
+     * @param fields The array of root fields to render as FormElements.
+     * @returns A fully populated sap.ui.layout.form.SimpleForm.
+     */
+    public static build(fields: IFieldMetadata[]): SimpleForm {
+        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
+        });
+
+        const registry = PluginRegistry.getInstance();
+
+        fields.forEach((field) => {
+            // Respect Fiori accessibility standards by enforcing the required flag on labels
+            const label = new Label({
+                text: field.label,
+                required: field.isRequired
+            });
+
+            // Instantiate the correct plugin for the data type
+            const plugin = registry.getPlugin(field.type);
+            
+            // In the isolated state manager architecture, the binding path maps exactly to the fieldName.
+            const control = plugin.render(field, `/${field.fieldName}`);
+
+            form.addContent(label);
+            form.addContent(control);
+        });
+
+        return form;
+    }
+}

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

@@ -0,0 +1,102 @@
+/**
+ * @file TableLayout.ts
+ * @description Generates a responsive SAP Fiori Table layout.
+ */
+
+import Table from "sap/m/Table";
+import Column from "sap/m/Column";
+import Text from "sap/m/Text";
+import ColumnListItem from "sap/m/ColumnListItem";
+import Toolbar from "sap/m/Toolbar";
+import Title from "sap/m/Title";
+import ToolbarSpacer from "sap/m/ToolbarSpacer";
+import Button from "sap/m/Button";
+import JSONModel from "sap/ui/model/json/JSONModel";
+import { ITableMetadata, IFieldMetadata } from "../interfaces/ISchema";
+import { PluginRegistry } from "../core/PluginRegistry";
+import Control from "sap/ui/core/Control";
+
+/**
+ * Utility class strictly for constructing sap.m.Table structures with dynamic pop-in vectors.
+ */
+export class TableLayout {
+    /**
+     * Builds a responsive Table, dynamically calculating column priorities.
+     * @param tableMeta The metadata defining the table's columns and nested fields.
+     * @returns A fully constructed sap.m.Table ready to be bound to a list array.
+     */
+    public static build(tableMeta: ITableMetadata): Table {
+        const table = new Table({
+            headerToolbar: new Toolbar({
+                content: [
+                    new Title({ text: tableMeta.label || tableMeta.tableName }),
+                    new ToolbarSpacer(),
+                    new Button({
+                        text: "Add Row",
+                        icon: "sap-icon://add",
+                        press: (oEvent: any) => {
+                            const btn = oEvent.getSource();
+                            const tbl = btn.getParent().getParent() as Table;
+                            const model = tbl.getModel("meta") as JSONModel;
+                            const path = `/${tableMeta.tableName}`;
+                            const data = model.getProperty(path) || [];
+                            data.push({}); // append empty row
+                            model.setProperty(path, data);
+                        }
+                    })
+                ]
+            }),
+            fixedLayout: false, // Allows native UI5 column width calculations
+            mode: "Delete",
+            delete: (oEvent: any) => {
+                const item = oEvent.getParameter("listItem");
+                const path = item.getBindingContext("meta").getPath(); // e.g. "/Contacts/0"
+                const model = item.getModel("meta") as JSONModel;
+                
+                const parts = path.split("/");
+                const index = parseInt(parts.pop() || "0", 10);
+                const arrayPath = parts.join("/");
+                
+                const data = model.getProperty(arrayPath);
+                data.splice(index, 1);
+                model.setProperty(arrayPath, data);
+            }
+        });
+
+        const templateCells: Control[] = [];
+        const registry = PluginRegistry.getInstance();
+
+        tableMeta.fields.forEach((field: IFieldMetadata) => {
+            // Build the column header
+            const column = new Column({
+                header: new Text({ text: field.label }),
+                // Fiori UX: High priority for primary keys so they don't pop-in too early
+                demandPopin: !field.isKey, 
+                minScreenWidth: field.isKey ? "" : "Tablet",
+                popinDisplay: "Inline"
+            });
+            table.addColumn(column);
+
+            // Instantiate the cell template (plugin)
+            const plugin = registry.getPlugin(field.type);
+            
+            // In table lists, the binding path is relative to the row's context context (e.g. "{fieldName}")
+            const control = plugin.render(field, field.fieldName);
+            templateCells.push(control);
+        });
+
+        // Create the row template and bind it to the table via the tableName array path
+        const rowTemplate = new ColumnListItem({
+            cells: templateCells
+        });
+
+        // The absolute binding path from the StateManager for this table (using the named model 'meta')
+        table.bindItems({
+            path: `meta>/${tableMeta.tableName}`,
+            template: rowTemplate,
+            templateShareable: false
+        });
+
+        return table;
+    }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * @file library.ts
+ * @description Standard SAP UI5 library registration file. Exposes the MetaUI namespace 
+ * and automatically bootstraps the internal PluginRegistry.
+ */
+
+import Core from "sap/ui/core/Core";
+import { PluginRegistry } from "./core/PluginRegistry";
+import { StringPlugin } from "./plugins/StringPlugin";
+import { NumberPlugin } from "./plugins/NumberPlugin";
+import { BooleanPlugin } from "./plugins/BooleanPlugin";
+import { DropdownPlugin } from "./plugins/DropdownPlugin";
+import { DatePlugin } from "./plugins/DatePlugin";
+
+// Delegate to standard library registration
+Core.initLibrary({
+    name: "nz.co.siliconst.ui5.metaui",
+    version: "1.0.0",
+    dependencies: [
+        "sap.ui.core",
+        "sap.m",
+        "sap.ui.layout",
+        "sap.ui.table"
+    ],
+    controls: [
+        "nz.co.siliconst.ui5.metaui.controls.GeneratorHost"
+    ],
+    elements: [],
+    interfaces: []
+});
+
+/**
+ * Global Bootstrapper: Maps all standard primitive types to their respective plugins.
+ */
+const registry = PluginRegistry.getInstance();
+registry.register("string", StringPlugin);
+registry.register("number", NumberPlugin);
+registry.register("boolean", BooleanPlugin);
+registry.register("dropdown", DropdownPlugin);
+registry.register("date", DatePlugin);
+
+// Exporting window object safely for UI5 compatibility if needed
+export default (window as any)["nz"]["co"]["siliconst"]["ui5"]["metaui"];

package/src/nz/co/siliconst/ui5/metaui/plugins/BasePlugin.ts

@@ -0,0 +1,58 @@
+/**
+ * @file BasePlugin.ts
+ * @description Abstract foundation for all MetaUI plugins, enforcing lifecycle hooks.
+ */
+
+import { IPlugin } from "../interfaces/IPlugin";
+import { IFieldMetadata } from "../interfaces/ISchema";
+import { EventBus } from "../core/EventBus";
+import Control from "sap/ui/core/Control";
+
+/**
+ * Abstract class providing baseline properties and event publishing hooks for all UI5 controls.
+ */
+export abstract class BasePlugin implements IPlugin {
+    /** The actual generated UI5 control. */
+    protected control: Control | null = null;
+    /** The schema configuration associated with this specific field. */
+    protected metadata: IFieldMetadata | null = null;
+
+    /**
+     * Must be implemented by concrete classes to generate the specific control.
+     * @param fieldMetadata The immutable schema configuration.
+     * @param bindingPath The exact model path where this field's data is stored.
+     */
+    public abstract render(fieldMetadata: IFieldMetadata, bindingPath: string): Control;
+
+    /**
+     * Must be implemented by concrete classes to run data integrity checks.
+     */
+    public abstract validate(): boolean;
+
+    /**
+     * Triggered by the ConditionEngine when cross-field rules alter this field's metadata.
+     * @param newMetadata The dynamically updated rules.
+     */
+    public onStateChange(newMetadata: IFieldMetadata): void {
+        this.metadata = newMetadata;
+        this.applyState();
+    }
+
+    /**
+     * Abstract hook for concrete plugins to re-bind their visibility or read-only states natively.
+     */
+    protected abstract applyState(): void;
+
+    /**
+     * Utility method for concrete plugins to easily broadcast changes to the EventBus.
+     * @param newValue The newly entered/selected value.
+     */
+    protected publishChange(newValue: any): void {
+        if (this.metadata) {
+            EventBus.getInstance().publishFieldChange({
+                fieldName: this.metadata.fieldName,
+                newValue: newValue
+            });
+        }
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/BooleanPlugin.ts

@@ -0,0 +1,42 @@
+/**
+ * @file BooleanPlugin.ts
+ * @description Renders a sap.m.Switch for boolean states.
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IFieldMetadata } from "../interfaces/ISchema";
+import Switch from "sap/m/Switch";
+import Control from "sap/ui/core/Control";
+
+/**
+ * Handles rendering logic for toggleable booleans.
+ */
+export class BooleanPlugin extends BasePlugin {
+    public render(fieldMetadata: IFieldMetadata, bindingPath: string): Control {
+        this.metadata = fieldMetadata;
+        
+        this.control = new Switch({
+            state: `{meta>${bindingPath}}`,
+            enabled: !fieldMetadata.isReadOnly,
+            change: (oEvent: any) => {
+                const val = oEvent.getParameter("state");
+                this.publishChange(val);
+                this.validate();
+            }
+        });
+
+        return this.control;
+    }
+
+    public validate(): boolean {
+        // Boolean switches inherently have a state (true/false) so they rarely fail validation.
+        return true;
+    }
+
+    protected applyState(): void {
+        if (this.control && this.metadata) {
+            const sw = this.control as Switch;
+            sw.setEnabled(!this.metadata.isReadOnly);
+        }
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/DatePlugin.ts

@@ -0,0 +1,63 @@
+/**
+ * @file DatePlugin.ts
+ * @description Renders a sap.m.DatePicker natively bound to ISO date strings.
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IFieldMetadata } from "../interfaces/ISchema";
+import DatePicker from "sap/m/DatePicker";
+import Control from "sap/ui/core/Control";
+
+/**
+ * Handles rendering logic for Date strings.
+ */
+export class DatePlugin extends BasePlugin {
+    public render(fieldMetadata: IFieldMetadata, bindingPath: string): Control {
+        this.metadata = fieldMetadata;
+        
+        this.control = new DatePicker({
+            value: `{meta>${bindingPath}}`,
+            valueFormat: "yyyy-MM-dd",
+            displayFormat: "long",
+            editable: !fieldMetadata.isReadOnly,
+            required: fieldMetadata.isRequired,
+            change: (oEvent: any) => {
+                const val = oEvent.getParameter("value");
+                this.publishChange(val);
+                this.validate();
+            }
+        });
+
+        return this.control;
+    }
+
+    public validate(): boolean {
+        if (!this.control || !this.metadata) return true;
+        const dp = this.control as DatePicker;
+        const isValid = dp.isValidValue();
+        const val = dp.getValue();
+
+        if (this.metadata.isRequired && (!val || val.trim() === "")) {
+            dp.setValueState("Error" as any);
+            dp.setValueStateText("A valid date is required.");
+            return false;
+        }
+
+        if (val && !isValid) {
+            dp.setValueState("Error" as any);
+            dp.setValueStateText("Invalid date format.");
+            return false;
+        }
+
+        dp.setValueState("None" as any);
+        return true;
+    }
+
+    protected applyState(): void {
+        if (this.control && this.metadata) {
+            const dp = this.control as DatePicker;
+            dp.setEditable(!this.metadata.isReadOnly);
+            dp.setRequired(this.metadata.isRequired);
+        }
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/DropdownPlugin.ts

@@ -0,0 +1,65 @@
+/**
+ * @file DropdownPlugin.ts
+ * @description Renders a sap.m.Select utilizing the schema's valueHelp structure.
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IFieldMetadata } from "../interfaces/ISchema";
+import Select from "sap/m/Select";
+import Item from "sap/ui/core/Item";
+import Control from "sap/ui/core/Control";
+
+/**
+ * Handles rendering logic for dropdown inputs.
+ */
+export class DropdownPlugin extends BasePlugin {
+    public render(fieldMetadata: IFieldMetadata, bindingPath: string): Control {
+        this.metadata = fieldMetadata;
+        
+        const select = new Select({
+            selectedKey: `{meta>${bindingPath}}`,
+            enabled: !fieldMetadata.isReadOnly,
+            change: (oEvent: any) => {
+                const item = oEvent.getParameter("selectedItem");
+                const val = item ? item.getKey() : "";
+                this.publishChange(val);
+                this.validate();
+            }
+        });
+
+        if (fieldMetadata.valueHelp && Array.isArray(fieldMetadata.valueHelp)) {
+            if (!fieldMetadata.isRequired) {
+                select.addItem(new Item({ key: "", text: "--- Select ---" }));
+            }
+            
+            fieldMetadata.valueHelp.forEach(vh => {
+                select.addItem(new Item({ key: vh.key, text: vh.text }));
+            });
+        }
+
+        this.control = select;
+        return this.control;
+    }
+
+    public validate(): boolean {
+        if (!this.control || !this.metadata) return true;
+        const select = this.control as Select;
+        const val = select.getSelectedKey();
+
+        if (this.metadata.isRequired && (!val || val.trim() === "")) {
+            select.setValueState("Error" as any);
+            select.setValueStateText("Selection is required.");
+            return false;
+        }
+
+        select.setValueState("None" as any);
+        return true;
+    }
+
+    protected applyState(): void {
+        if (this.control && this.metadata) {
+            const select = this.control as Select;
+            select.setEnabled(!this.metadata.isReadOnly);
+        }
+    }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * @file NumberPlugin.ts
+ * @description Renders a sap.m.StepInput for numeric data.
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IFieldMetadata } from "../interfaces/ISchema";
+import StepInput from "sap/m/StepInput";
+import Control from "sap/ui/core/Control";
+
+/**
+ * Handles rendering and logic for numeric inputs with precision and scale.
+ */
+export class NumberPlugin extends BasePlugin {
+    public render(fieldMetadata: IFieldMetadata, bindingPath: string): Control {
+        this.metadata = fieldMetadata;
+        
+        this.control = new StepInput({
+            value: `{meta>${bindingPath}}`,
+            displayValuePrecision: fieldMetadata.scale || 0,
+            editable: !fieldMetadata.isReadOnly,
+            required: fieldMetadata.isRequired,
+            change: (oEvent: any) => {
+                const val = oEvent.getParameter("value");
+                this.publishChange(val);
+                this.validate();
+            }
+        });
+
+        return this.control;
+    }
+
+    public validate(): boolean {
+        if (!this.control || !this.metadata) return true;
+        const input = this.control as StepInput;
+        const val = input.getValue();
+
+        if (this.metadata.isRequired && (val === null || val === undefined)) {
+            input.setValueState("Error" as any);
+            input.setValueStateText("This field is required.");
+            return false;
+        }
+
+        input.setValueState("None" as any);
+        return true;
+    }
+
+    protected applyState(): void {
+        if (this.control && this.metadata) {
+            const input = this.control as StepInput;
+            input.setEditable(!this.metadata.isReadOnly);
+            input.setRequired(this.metadata.isRequired);
+        }
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/plugins/StringPlugin.ts

@@ -0,0 +1,55 @@
+/**
+ * @file StringPlugin.ts
+ * @description Renders a sap.m.Input for string data and validates lengths.
+ */
+
+import { BasePlugin } from "./BasePlugin";
+import { IFieldMetadata } from "../interfaces/ISchema";
+import Input from "sap/m/Input";
+import Control from "sap/ui/core/Control";
+
+/**
+ * Handles rendering and logic for basic text inputs.
+ */
+export class StringPlugin extends BasePlugin {
+    public render(fieldMetadata: IFieldMetadata, bindingPath: string): Control {
+        this.metadata = fieldMetadata;
+        
+        this.control = new Input({
+            value: `{meta>${bindingPath}}`,
+            maxLength: fieldMetadata.maxLength || 0,
+            editable: !fieldMetadata.isReadOnly,
+            required: fieldMetadata.isRequired,
+            change: (oEvent: any) => {
+                const val = oEvent.getParameter("value");
+                this.publishChange(val);
+                this.validate();
+            }
+        });
+
+        return this.control;
+    }
+
+    public validate(): boolean {
+        if (!this.control || !this.metadata) return true;
+        const input = this.control as Input;
+        const val = input.getValue();
+
+        if (this.metadata.isRequired && (!val || val.trim() === "")) {
+            input.setValueState("Error" as any);
+            input.setValueStateText("This field is required.");
+            return false;
+        }
+
+        input.setValueState("None" as any);
+        return true;
+    }
+
+    protected applyState(): void {
+        if (this.control && this.metadata) {
+            const input = this.control as Input;
+            input.setEditable(!this.metadata.isReadOnly);
+            input.setRequired(this.metadata.isRequired);
+        }
+    }
+}