@siliconst/metaui 1.4.44 → 2.0.0

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

@@ -0,0 +1,48 @@
+/**
+ * @file IEngineHost.ts
+ * @description Contract defining what the Engine requires from its hosting container.
+ */
+
+import Control from "sap/ui/core/Control";
+import { StateManager } from "../core/StateManager";
+import { ISchema } from "./ISchema";
+
+/**
+ * Contract defining what the Engine requires from its hosting container (GeneratorHost).
+ */
+export interface IEngineHost {
+    /** Retrieves the central StateManager managing the active data models. */
+    getStateManager(): StateManager | null;
+
+    /** Retrieves the current active schema for the host. */
+    getParsedSchema?(): ISchema | null;
+
+    /** Resolves a `$ref` pointer against the host's normalized schemaDefinitions dictionary. */
+    getSchemaDefinition?(refPath: string): ISchema | undefined;
+
+    /** Returns the full normalized schemaDefinitions dictionary. */
+    getSchemaDefinitions?(): Record<string, ISchema> | undefined;
+
+    /**
+     * Returns the layout budget in force on the host, so a nested modal host inherits it explicitly.
+     * Before this existed the budget reached a nested host only because `LayoutScorer` wrote
+     * `ui.layoutBudget` onto the schema node and `NestedDialogPlugin` copied the node's `ui` block
+     * onto the modal sub-schema - layout state travelling through the consumer's schema.
+     */
+    getLayoutBudget?(): number;
+
+    /** Fires a UI5 event on the host control. */
+    fireEvent?(eventName: string, parameters?: Record<string, unknown>): unknown;
+
+    /** Immediately flushes any pending debounced policy evaluation. */
+    evaluatePoliciesNow?(): void;
+
+    /** Resets the policy differential matrix and immediately re-evaluates all policies. */
+    resetAndEvaluatePoliciesNow?(): void;
+
+    /** The active JSONModel name where data is bound. */
+    activeModelName: string;
+
+    /** The root generated layout control. */
+    generatedContent: Control | null;
+}

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

@@ -1,21 +1,28 @@
-/**
- * @file ILayoutManager.ts
- * @description Factory contract for generating UI5 layout containers (Forms/Tables).
- */
-
-import Control from "sap/ui/core/Control";
-import { IPropertyMetadata } from "./ISchema";
-
-import { IPlugin } from "./IPlugin";
-
-export interface ILayoutManager {
-    /**
-     * Renders a UI container based on the provided schema.
-     * @param schema The schema defining the layout content.
-     * @param modelName The UI5 JSONModel name for data binding.
-     * @param engine Reference back to the Engine for recursive internal field generation.
-     * @param onSubmit Callback to trigger form submission from the layout natively (e.g. Wizard complete)
-     * @param bindingPath Optional path to bind the layout (e.g. for nested array tables)
-     */
-    render(schema: import("./ISchema").ISchema, modelName: string, engine: import("../core/Engine").Engine, onSubmit?: () => void, bindingPath?: string): Control;
-}
+/**
+ * @file ILayoutManager.ts
+ * @description Factory contract for generating UI5 layout containers (Forms/Tables/Wizards).
+ */
+
+import Control from "sap/ui/core/Control";
+import { ISchema } from "./ISchema";
+import type { Engine } from "../core/Engine";
+
+/**
+ * Contract implemented by all layout strategies (`FormLayout`, `TableLayout`, `WizardLayout`, `CompactLayout`).
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.interfaces
+ * @public
+ */
+export interface ILayoutManager {
+    /**
+     * Renders a UI container based on the provided schema.
+     *
+     * @param schema The schema defining the layout content.
+     * @param modelName The UI5 JSONModel name for data binding.
+     * @param engine Reference back to the Engine for recursive internal field generation.
+     * @param onSubmit Callback to trigger form submission from the layout natively (e.g. Wizard complete).
+     * @param bindingPath Optional path to bind the layout (e.g. for nested array tables).
+     * @returns {Control} The constructed UI5 layout container.
+     */
+    render(schema: ISchema, modelName: string, engine: Engine, onSubmit?: () => void, bindingPath?: string): Control;
+}

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

@@ -1,39 +1,83 @@
-/**
- * @file IPipeline.ts
- * @description Interfaces for the generic data manipulation pipeline (Formatters, Parsers, Validators).
- */
-
-export interface IFormatter {
-    /**
-     * Formats raw JSON model data into a UI-friendly string.
-     * @param rawValue The raw value from the JSON payload.
-     * @param args Optional arguments provided in the schema.
-     * @returns The formatted string for the UI control.
-     */
-    format(rawValue: unknown, args?: unknown): string;
-}
-
-export interface IParser {
-    /**
-     * Parses UI-formatted strings back into raw data types.
-     * @param uiValue The value extracted from the UI control.
-     * @param args Optional arguments provided in the schema.
-     * @returns The raw typed value for the JSON payload.
-     */
-    parse(uiValue: unknown, args?: unknown): unknown;
-}
-
-export interface IValidationResult {
-    isValid: boolean;
-    errorMessage?: string;
-}
-
-export interface IValidator {
-    /**
-     * Validates parsed data before it enters the JSON model.
-     * @param parsedValue The cleaned data to validate.
-     * @param args Optional arguments provided in the schema (e.g. max length number)
-     * @returns IValidationResult containing status and optional error message.
-     */
-    validate(parsedValue: unknown, args?: unknown): IValidationResult;
-}
+/**
+ * @file IPipeline.ts
+ * @description Interfaces for the generic data manipulation pipeline (Formatters, Parsers, Validators).
+ */
+
+import { IPropertyMetadata } from "./ISchema";
+
+/**
+ * Contract for pipeline formatters that transform raw model values into UI display strings.
+ */
+export interface IFormatter {
+    /**
+     * Formats raw JSON model data into a UI-friendly string.
+     * @param rawValue The raw value from the JSON payload.
+     * @param args Optional arguments provided in the schema.
+     * @returns The formatted string for the UI control.
+     */
+    format(rawValue: unknown, args?: unknown): string;
+
+    /**
+     * Optional reverse parser that converts UI-formatted strings back into raw model values.
+     * When implemented, `PipelineManager` treats the formatter as presentational (reversible).
+     * @param uiValue The value extracted from the UI control.
+     * @param args Optional arguments provided in the schema.
+     * @returns The raw typed value for the JSON payload.
+     */
+    parse?(uiValue: unknown, args?: unknown): unknown;
+}
+
+/**
+ * Contract for pipeline parsers that convert UI input strings back into typed model values.
+ */
+export interface IParser {
+    /**
+     * Parses UI-formatted strings back into raw data types.
+     * @param uiValue The value extracted from the UI control.
+     * @param args Optional arguments provided in the schema.
+     * @returns The raw typed value for the JSON payload.
+     */
+    parse(uiValue: unknown, args?: unknown): unknown;
+}
+
+/**
+ * Result returned by a single pipeline validator execution.
+ */
+export interface IValidationResult {
+    isValid: boolean;
+    errorMessage?: string;
+}
+
+/**
+ * Result returned by `IValidator.extractRule` when inspecting a schema property descriptor.
+ */
+export interface IValidatorRuleExtraction {
+    /** True if this validator plugin should run for the given schema property. */
+    readonly active: boolean;
+    /** Optional constraint arguments extracted from the schema property. */
+    readonly args?: unknown;
+}
+
+/**
+ * Contract for synchronous data validators registered in the {@link PipelineManager}.
+ */
+export interface IValidator {
+    /**
+     * Validates parsed data before it enters the JSON model.
+     * @param parsedValue The cleaned data to validate.
+     * @param args Optional arguments provided in the schema (e.g. max length number).
+     * @returns IValidationResult containing status and optional error message.
+     */
+    validate(parsedValue: unknown, args?: unknown): IValidationResult;
+
+    /**
+     * Optional self-activation hook allowing a validator plugin to inspect `IPropertyMetadata`
+     * and declare whether it applies to the field and with what arguments.
+     * Enforces the Open/Closed Principle in `PipelineManager.assembleAndExecute`.
+     *
+     * @param propMeta The schema property descriptor.
+     * @param isDynamicallyRequired Optional dynamic `required` state override.
+     * @returns {IValidatorRuleExtraction} Activation state and extracted arguments.
+     */
+    extractRule?(propMeta: IPropertyMetadata, isDynamicallyRequired?: boolean): IValidatorRuleExtraction;
+}

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

@@ -1,82 +1,146 @@
-/**
- * @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 { IPropertyMetadata } from "./ISchema";
-
-export interface IPluginValidationResult {
-    isValid: boolean;
-    errorMessage?: string;
-    fieldKey?: string;
-    fieldLabel?: string;
-}
-
-/**
- * Standardized hooks for the Policy-Based Rule Engine (PBRE) to dynamically mutate visual state.
- */
-export interface IPluginStateReceiver {
-    applyError?(errorMessage: string): void;
-    clearError?(): void;
-    applyVisibility?(isVisible: boolean): void;
-    applyRequired?(isRequired: boolean): void;
-    applyEditable?(isEditable: boolean): void;
-}
-
-export interface IPlugin extends IPluginStateReceiver {
-    /**
-     * Instructs the plugin whether to delegate visual error states to the global MessageManager.
-     * @param useMessageManager True if the global MessageManager is active.
-     */
-    setUseMessageManager?(useMessageManager: boolean): void;
-
-    /**
-     * Instantiates the raw UI5 control and binds it to the specified data model.
-     * 
-     * @param fieldMetadata The JSON Schema defining the field's constraints and UI hints.
-     * @param bindingPath The specific JSON path representing the field within the payload.
-     * @param modelName The UI5 JSONModel alias used for data binding (defaults to 'meta').
-     * @param engineScopeId The deterministic scope ID provided by the Engine.
-     * @param onChange The callback fired natively when a field value blur/change occurs.
-     * @returns {Control} The generated UI5 control ready to be mounted.
-     */
-    render(fieldMetadata: IPropertyMetadata, bindingPath: string, modelName?: string, engineScopeId?: string, onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void, model?: unknown): Control;
-
-    /**
-     * Triggers the internal validation pipeline for this specific plugin instance.
-     * 
-     * @returns {IPluginValidationResult} The structural validity state and error messages.
-     */
-    validate(): IPluginValidationResult;
-
-    /**
-     * Executes when the ConditionEngine pushes dynamic metadata mutations to the field.
-     * 
-     * @param newMetadata The mutated schema metadata.
-     */
-    onStateChange(newMetadata: IPropertyMetadata): void;
-
-    /**
-     * Optionally allows the plugin to natively manage its own UI control's visual ValueState (e.g., red borders).
-     * Used when the global MessageManager is disabled.
-     * 
-     * @param isValid Whether the field passed validation.
-     * @param errorMessage The error message to display if invalid.
-     */
-    setVisualValidationState?(isValid: boolean, errorMessage?: string): void;
-
-    /**
-     * Optional lifecycle hook executed when the parent layout is destroyed.
-     * Plugins must use this to destroy isolated JSONModels, custom EventBus listeners, 
-     * or embedded Dialogs to prevent memory leaks in the SAP Fiori Launchpad.
-     */
-    destroy?(): void;
-
-    /**
-     * Injects the global editable mode context into the plugin before rendering.
-     * @param editable True if the plugin should render in an editable mode.
-     */
-    setEditable?(editable: boolean): void;
-}
+/**
+ * @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 Label from "sap/m/Label";
+import Model from "sap/ui/model/Model";
+import { IPropertyMetadata, ISchema } from "./ISchema";
+import type { PluginRegistry } from "../core/PluginRegistry";
+
+/**
+ * Result returned when a control plugin executes its internal validation pipeline.
+ */
+export interface IPluginValidationResult {
+    isValid: boolean;
+    errorMessage?: string;
+    fieldKey?: string;
+    fieldLabel?: string;
+}
+
+/**
+ * Contextual callbacks and services injected into a plugin by the orchestrating {@link Engine}.
+ * Replaces parent-tree walking and singleton lookups with explicit dependency injection.
+ */
+export interface IPluginEngineContext {
+    /** The active PluginRegistry for this engine instance. */
+    pluginRegistry: PluginRegistry;
+    /** Resolves a `$ref` pointer (e.g. `#/definitions/Address`) against the host's definitions dictionary. */
+    resolveSchemaRef?: (refPath: string) => ISchema | undefined;
+    /** Resolves a `$ref` pointer against the host's definitions dictionary. */
+    getSchemaDefinition: (refPath: string) => ISchema | undefined;
+    /** Returns the full normalized definitions dictionary from the host. */
+    getSchemaDefinitions: () => Record<string, ISchema> | undefined;
+    /** Returns the host's layout budget, which a nested modal host inherits explicitly rather than through the schema. */
+    getLayoutBudget?: () => number;
+    /** Returns the active JSONModel bound to the Engine. */
+    getModel: () => Model | undefined;
+    /** Triggers the host's form submission pipeline. */
+    onSubmit?: () => void;
+    /** Reports or clears a localized schema validation error in the ValidationLedger. */
+    reportSchemaError?: (fieldPath: string, errorMessage: string | null) => void;
+    /** Clears all validation ledger entries under a given path prefix. */
+    clearValidationPrefix?: (prefix: string) => void;
+    /** Clears all validation errors across the Engine and active plugins. */
+    clearValidationErrors?: () => void;
+}
+
+/**
+ * Standardized hooks for the Policy-Based Rule Engine (PBRE) to dynamically mutate visual state.
+ * Implemented by `PluginStateBase` and inherited by every control plugin via `BasePlugin`.
+ */
+export interface IPluginStateReceiver {
+    applyError(errorMessage: string): void;
+    clearError(): void;
+    applyVisibility(isVisible: boolean): void;
+    applyRequired(isRequired: boolean): void;
+    applyEditable(isEditable: boolean): void;
+    isVisible(): boolean;
+    getFieldLabel(): string | undefined;
+    getControlId(): string | undefined;
+    setAssociatedLabel(label: Label): void;
+}
+
+/**
+ * Core contract for all UI5 control, action, and datasource generation plugins in MetaUI.
+ */
+export interface IPlugin extends IPluginStateReceiver {
+    /**
+     * Instructs the plugin whether to delegate visual error states to the global MessageManager.
+     * @param useMessageManager True if the global MessageManager is active.
+     */
+    setUseMessageManager?(useMessageManager: boolean): void;
+
+    /**
+     * Injects engine-scoped services (registry, `$ref` resolver, submit callback) into the plugin.
+     * @param context The engine context.
+     */
+    setEngineContext(context: IPluginEngineContext): void;
+
+    /**
+     * Instantiates the raw UI5 control and binds it to the specified data model.
+     *
+     * @param fieldMetadata The JSON Schema defining the field's constraints and UI hints.
+     * @param bindingPath The specific JSON path representing the field within the payload.
+     * @param modelName The UI5 JSONModel alias used for data binding (defaults to 'meta').
+     * @param engineScopeId The deterministic scope ID provided by the Engine.
+     * @param onChange The callback fired natively when a field value blur/change occurs.
+     * @param model Optional reference to the active JSONModel.
+     * @returns {Control} The generated UI5 control ready to be mounted.
+     */
+    render(
+        fieldMetadata: IPropertyMetadata,
+        bindingPath: string,
+        modelName?: string,
+        engineScopeId?: string,
+        onChange?: (isValid: boolean, fieldKey?: string, errorMessage?: string, controlId?: string) => void,
+        model?: unknown
+    ): Control;
+
+    /**
+     * Triggers the internal validation pipeline for this specific plugin instance.
+     *
+     * @returns {IPluginValidationResult} The structural validity state and error messages.
+     */
+    validate(): IPluginValidationResult;
+
+    /**
+     * Executes when the ConditionEngine pushes dynamic metadata mutations to the field.
+     *
+     * @param newMetadata The mutated schema metadata.
+     */
+    onStateChange(newMetadata: IPropertyMetadata): void;
+
+    /**
+     * Updates the plugin's UI control visual ValueState (e.g., red borders).
+     *
+     * @param isValid Whether the field passed validation.
+     * @param errorMessage The error message to display if invalid.
+     */
+    setVisualValidationState(isValid: boolean, errorMessage?: string): void;
+
+    /**
+     * Lifecycle hook executed when the parent layout is destroyed.
+     * Plugins use this to destroy isolated JSONModels, custom EventBus listeners,
+     * or embedded Dialogs to prevent memory leaks in the SAP Fiori Launchpad.
+     */
+    destroy(): void;
+
+    /**
+     * Injects the global editable mode context into the plugin before rendering.
+     * @param editable True if the plugin should render in an editable mode.
+     */
+    setEditable(editable: boolean): void;
+
+    /**
+     * Dynamically updates a specific state property (`visible`, `editable`, `required`, `valid`) at runtime.
+     */
+    setState(property: "visible" | "editable" | "required" | "valid", value: boolean, message?: string): void;
+
+    /**
+     * Resolves a nested child plugin by its binding path when this plugin manages dynamic child plugins (e.g. `PolymorphicPlugin`).
+     */
+    getChildPluginByPath?(path: string): IPlugin | undefined;
+}

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

@@ -1,49 +1,57 @@
-/**
- * @file IPolicyPlugin.ts
- * @description Contracts for extending the PolicyEngine with custom evaluation and effect logic.
- * Enforces the Plugin-First architecture to prevent hardcoding rule sets.
- */
-
-import { PolicyEffectType } from "./ISchema";
-import { PropertyName } from "../core/PolicyEngine";
-
-/**
- * Resolves whether a specific schema condition passes or fails against the live UI data payload.
- */
-export interface IPolicyConditionPlugin {
-    /**
-     * Identifies if this plugin handles a specific condition key (e.g., "NumericGreaterThan", "StringEquals").
-     * @param conditionKey The key extracted from the IPolicyCondition block.
-     * @returns True if this plugin should evaluate the block, false otherwise.
-     */
-    canHandle(conditionKey: string): boolean;
-
-    /**
-     * Evaluates the condition payload against the live data.
-     * @param conditionPayload The arbitrary payload attached to the condition key (e.g., { "/Age": 18 }).
-     * @param data The live JSON model payload.
-     * @param resolvePointer A utility function injected by the orchestrator to safely resolve JSON paths against the data.
-     * @returns True if the condition is satisfied, false otherwise.
-     */
-    evaluate(conditionPayload: unknown, data: unknown, resolvePointer: (d: unknown, p: string) => unknown): boolean;
-}
-
-/**
- * Translates a semantic policy effect (e.g., "Hide", "Invalidate") into a strict binary structural property state.
- */
-export interface IPolicyEffectPlugin {
-    /**
-     * Identifies if this plugin translates a specific semantic effect string.
-     * @param effect The semantic string defined in the schema (e.g., "Hide", "Require").
-     * @returns True if this plugin owns the translation, false otherwise.
-     */
-    canHandle(effect: PolicyEffectType | string): boolean;
-
-    /**
-     * Resolves the effect into a concrete structural delta for the UI components.
-     * Automatically handles the symmetrical reversal if the condition is false.
-     * @param isConditionMet Whether the governing policy condition passed or failed.
-     * @returns An object containing the exact property to alter (e.g., "visibility") and its new boolean state.
-     */
-    resolveState(isConditionMet: boolean, originalEffect: PolicyEffectType | string): { property: PropertyName, value: boolean };
-}
+/**
+ * @file IPolicyPlugin.ts
+ * @description Contracts for extending the PolicyEngine with custom evaluation and effect logic.
+ * Enforces the Plugin-First architecture to prevent hardcoding rule sets.
+ */
+
+import { PolicyEffectType } from "./ISchema";
+import { PropertyName } from "../core/PolicyEngine";
+
+/**
+ * Resolves whether a specific schema condition passes or fails against the live UI data payload.
+ */
+export interface IPolicyConditionPlugin {
+    /**
+     * Optional legacy identifier for condition keys. `PolicyEngine` dispatches purely by registered
+     * operator key in `PluginRegistry.registerPolicyConditionPath`.
+     * @deprecated Dispatched by `PluginRegistry` operator key.
+     * @param conditionKey The key extracted from the IPolicyCondition block.
+     * @returns True if this plugin should evaluate the block, false otherwise.
+     */
+    canHandle?(conditionKey: string): boolean;
+
+    /**
+     * Evaluates the condition payload against the live data.
+     * @param conditionPayload The arbitrary payload attached to the condition key (e.g., { "/Age": 18 }).
+     * @param data The live JSON model payload.
+     * @param resolvePointer A utility function injected by the orchestrator to safely resolve JSON paths against the data.
+     * @returns True if the condition is satisfied, false otherwise.
+     */
+    evaluate(conditionPayload: unknown, data: unknown, resolvePointer: (d: unknown, p: string) => unknown): boolean;
+}
+
+/**
+ * Translates a semantic policy effect (e.g., "Hide", "Invalidate") into a strict binary structural property state.
+ */
+export interface IPolicyEffectPlugin {
+    /**
+     * Optional legacy identifier for effect keys. `PolicyEngine` dispatches purely by registered
+     * effect key in `PluginRegistry.registerPolicyEffectPath`.
+     * @deprecated Dispatched by `PluginRegistry` effect key.
+     * @param effect The semantic string defined in the schema (e.g., "Hide", "Require").
+     * @returns True if this plugin owns the translation, false otherwise.
+     */
+    canHandle?(effect: PolicyEffectType | string): boolean;
+
+    /**
+     * Resolves the effect into a concrete structural delta for the UI components.
+     * Automatically handles the symmetrical reversal if the condition is false.
+     * @param isConditionMet Whether the governing policy condition passed or failed.
+     * @param originalEffect The semantic effect string declared in the schema.
+     * @returns An object containing the exact property to alter (e.g., "visibility") and its new boolean state.
+     */
+    resolveState(
+        isConditionMet: boolean,
+        originalEffect: PolicyEffectType | string
+    ): { property: PropertyName; value: boolean };
+}