@siliconst/metaui 1.4.44 → 2.0.0

package/src/nz/co/siliconst/ui5/metaui/controls/host/delegates/PolicyDelegate.ts

@@ -0,0 +1,228 @@
+/**
+ * @file PolicyDelegate.ts
+ * @description Host delegate responsible for managing the PolicyEngine lifecycle,
+ * debouncing live field-change policy evaluations, and applying differential state
+ * mutations (visibility, validity, required, editable) to active plugins and table row cells.
+ */
+
+import { IPolicy } from "../../../interfaces/ISchema";
+import { PolicyEngine, IDeltaState } from "../../../core/PolicyEngine";
+import { PluginRegistry } from "../../../core/PluginRegistry";
+import { Engine } from "../../../core/Engine";
+import { StateManager } from "../../../core/StateManager";
+import { Logger } from "../../../utils/Logger";
+
+/**
+ * Delegate managing Policy-Based Rules Engine (PBRE) execution for `GeneratorHost`.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.controls.host.delegates
+ * @internal
+ */
+export class PolicyDelegate {
+    private policyEngine: PolicyEngine | null = null;
+    private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+    private onEvaluationComplete?: (anyValuePruned?: boolean) => void;
+
+    /**
+     * Initializes a new `PolicyDelegate`.
+     *
+     * @param onEvaluationComplete Optional hook invoked after policy evaluation finishes to sync host `isValid`.
+     */
+    constructor(onEvaluationComplete?: (anyValuePruned?: boolean) => void) {
+        this.onEvaluationComplete = onEvaluationComplete;
+    }
+
+    /**
+     * Cancels any pending debounced policy evaluation timer without clearing the active `PolicyEngine`.
+     */
+    public cancelPendingEvaluation(): void {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+    }
+
+    /**
+     * Initializes or clears the internal `PolicyEngine` instance based on the normalized schema's `uiPolicies`.
+     *
+     * @param policies Optional array of declarative policies from the normalized schema.
+     * @param pluginRegistry Optional injected `PluginRegistry` instance.
+     */
+    public configure(policies?: IPolicy[], pluginRegistry?: PluginRegistry): void {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        this.policyEngine =
+            policies && policies.length > 0 ? new PolicyEngine(policies, pluginRegistry) : null;
+    }
+
+    /**
+     * Returns whether an active `PolicyEngine` is configured.
+     *
+     * @returns {boolean} True if policies are active.
+     */
+    public hasPolicies(): boolean {
+        return this.policyEngine !== null;
+    }
+
+    /**
+     * Resets the internal `PolicyEngine` differential state matrix so the next evaluation emits full deltas.
+     */
+    public reset(): void {
+        this.policyEngine?.reset();
+    }
+
+    /**
+     * Schedules a debounced policy evaluation pass after a user field change.
+     *
+     * @param stateManager The active `StateManager` instance.
+     * @param engine The active `Engine` instance.
+     * @param delayMs Debounce delay in milliseconds (default `200`).
+     */
+    public scheduleEvaluation(
+        stateManager: StateManager | null,
+        engine: Engine | null,
+        delayMs: number = 200
+    ): void {
+        if (!this.policyEngine) {
+            return;
+        }
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.evaluateNow(stateManager, engine);
+        }, delayMs);
+    }
+
+    /**
+     * Applies a single policy delta to its target plugin or table row cell.
+     *
+     * A delta flagged `degraded` came from a policy whose condition the engine could not evaluate. It is a
+     * statement about a broken rule, not about the data, so it must never hide a field or prune its value:
+     * `StateManager.setProperty(target, undefined)` makes `extractPayload()` emit `undefined`, which
+     * `JSON.stringify` then drops, silently deleting the user's input from the submitted payload.
+     *
+     * @param delta The differential state mutation to apply.
+     * @param stateManager The active `StateManager` instance.
+     * @param engine The active `Engine` instance.
+     * @returns {boolean} True when the delta pruned a hidden field value out of the model.
+     */
+    private applyDelta(delta: IDeltaState, stateManager: StateManager, engine: Engine): boolean {
+        let valuePruned = false;
+        if (delta.property === "visibility" && delta.value === false) {
+            if (delta.degraded) {
+                Logger.error(
+                    `Refusing to hide '${delta.target}' and prune its value: the policy governing it could not be ` +
+                    `evaluated. Fix the policy condition; the field stays visible and its value is preserved.`,
+                    undefined,
+                    "PolicyDelegate"
+                );
+                return false;
+            }
+            stateManager.setProperty(delta.target, undefined);
+            engine.reportSchemaError(delta.target, null);
+            valuePruned = true;
+        }
+
+        const plugin = engine.getPluginByPath(delta.target);
+        if (!plugin) {
+            if (delta.property === "validity") {
+                engine.reportPolicyError(
+                    delta.target,
+                    delta.value ? null : delta.errorMessage || "Validation failed by policy"
+                );
+            } else {
+                engine.applyRowPolicyState(delta.target, delta.property, delta.value);
+            }
+            return valuePruned;
+        }
+
+        switch (delta.property) {
+            case "visibility":
+                if (plugin.applyVisibility) plugin.applyVisibility(delta.value);
+                engine.refreshFieldValidationState(delta.target);
+                break;
+            case "validity":
+                engine.reportPolicyError(
+                    delta.target,
+                    delta.value ? null : delta.errorMessage || "Validation failed by policy"
+                );
+                break;
+            case "required":
+                if (plugin.applyRequired) plugin.applyRequired(delta.value);
+                if (!delta.value) {
+                    const res = plugin.validate();
+                    if (res.isValid) {
+                        engine.reportSchemaError(delta.target, null);
+                    }
+                }
+                break;
+            case "editable":
+                if (plugin.applyEditable) plugin.applyEditable(delta.value);
+                break;
+        }
+        return valuePruned;
+    }
+
+    /**
+     * Immediately evaluates all active policies against the current payload and applies resulting deltas
+     * to the corresponding plugins or table row cells. Prunes hidden field values from the model.
+     *
+     * Isolation holds at three levels, so one bad rule cannot take out the rest of the form:
+     * `PolicyEngine.evaluate` wraps each individual policy, this method wraps the whole evaluation pass as a
+     * backstop, and each delta is applied inside its own `try`. A policy the engine could not evaluate emits
+     * `degraded` deltas, which {@link PolicyDelegate.applyDelta} refuses to let hide a field or prune its value.
+     *
+     * @param stateManager The active `StateManager` instance.
+     * @param engine The active `Engine` instance.
+     */
+    public evaluateNow(stateManager: StateManager | null, engine: Engine | null): void {
+        if (!this.policyEngine || !stateManager || !engine) {
+            return;
+        }
+        const payload = stateManager.extractPayload();
+        let deltas: IDeltaState[] = [];
+        try {
+            deltas = this.policyEngine.evaluate(payload);
+        } catch (e) {
+            Logger.error(
+                `Policy evaluation pass failed and emitted no deltas: ${e instanceof Error ? e.message : String(e)}`,
+                undefined,
+                "PolicyDelegate"
+            );
+        }
+        let anyValuePruned = false;
+
+        for (const delta of deltas) {
+            try {
+                if (this.applyDelta(delta, stateManager, engine)) {
+                    anyValuePruned = true;
+                }
+            } catch (e) {
+                Logger.error(
+                    `Failed to apply '${delta.property}' policy delta to '${delta.target}': ` +
+                    (e instanceof Error ? e.message : String(e)),
+                    undefined,
+                    "PolicyDelegate"
+                );
+            }
+        }
+
+        if (this.onEvaluationComplete) {
+            this.onEvaluationComplete(anyValuePruned);
+        }
+    }
+
+    /**
+     * Cleans up any pending debounce timers and releases the `PolicyEngine` reference.
+     */
+    public destroy(): void {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        this.policyEngine = null;
+    }
+}

package/src/nz/co/siliconst/ui5/metaui/controls/host/delegates/SchemaResolutionDelegate.ts

@@ -0,0 +1,223 @@
+/**
+ * @file SchemaResolutionDelegate.ts
+ * @description Host delegate for DynamicHost that resolves remote URL schemas via SchemaProvider,
+ * translates raw schemas via SchemaBuilderRegistry, and wires inner GeneratorHost properties and events.
+ */
+
+import Event from "sap/ui/base/Event";
+import MessageToast from "sap/m/MessageToast";
+import GeneratorHost from "../GeneratorHost";
+import InferredGeneratorHost from "../InferredGeneratorHost";
+import { SchemaBuilderRegistry } from "../../../core/SchemaBuilderRegistry";
+import { SchemaProvider } from "../../../services/SchemaProvider";
+import { Logger } from "../../../utils/Logger";
+import { isRecord } from "../../../utils/TypeGuards";
+import { DataSyncDelegate } from "./DataSyncDelegate";
+import type DynamicHost from "../../DynamicHost";
+
+/**
+ * Delegate managing remote schema resolution and inner `GeneratorHost` initialization for `DynamicHost`.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.controls.host.delegates
+ * @internal
+ */
+export class SchemaResolutionDelegate {
+    private fetchRequestId: number = 0;
+    private fetchPromise: Promise<void> | null = null;
+    private fetchUrl: string | null = null;
+
+    constructor(private readonly facade: DynamicHost) {}
+
+    /**
+     * Returns any currently active remote schema fetch promise so `openInDialog` can await it.
+     * @returns {Promise<void> | null} The active fetch promise, or `null`.
+     */
+    public getFetchPromise(): Promise<void> | null {
+        return this.fetchPromise;
+    }
+
+    /**
+     * Checks whether the provided `data` or `dataJson` contains a non-empty payload for inference.
+     *
+     * @param data Raw `data` property value.
+     * @param dataJson Raw `dataJson` string value.
+     * @returns {boolean} True if at least one non-empty data source is available.
+     */
+    public isDataNonEmpty(data: unknown, dataJson: unknown): boolean {
+        if (typeof dataJson === "string") {
+            const trimmed = dataJson.trim();
+            if (trimmed.length > 0 && trimmed !== "{}" && trimmed !== "[]") {
+                return true;
+            }
+        }
+        if (data !== null && data !== undefined) {
+            if (typeof data === "string") {
+                const trimmed = data.trim();
+                return trimmed.length > 0 && trimmed !== "{}" && trimmed !== "[]";
+            }
+            if (Array.isArray(data)) {
+                return data.length > 0;
+            }
+            if (isRecord(data)) {
+                return Object.keys(data).length > 0;
+            }
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Evaluates `schemaDefinition` on the facade. If it is a remote HTTP(S) URL, initiates an async fetch
+     * and returns `null`. Otherwise translates the schema via `SchemaBuilderRegistry` and spawns a configured
+     * `GeneratorHost` or `InferredGeneratorHost` when either schema or data is present.
+     *
+     * @returns {GeneratorHost | null} The initialized inner `GeneratorHost`, or `null` if waiting on async fetch or empty.
+     */
+    public resolveAndSpawnInnerHost(): GeneratorHost | null {
+        const schemaRaw: unknown = this.facade.getBaseProperty("schemaDefinition");
+
+        if (typeof schemaRaw === "string" && (schemaRaw.startsWith("http://") || schemaRaw.startsWith("https://"))) {
+            // `DynamicHost.setProperty` already starts the fetch when the URL is assigned. Only start one here
+            // when nothing is in flight for this exact URL, so a remote schema costs a single request.
+            if (this.fetchPromise === null || this.fetchUrl !== schemaRaw) {
+                this.startRemoteFetch(schemaRaw);
+            }
+            return null;
+        }
+
+        const schema = this.parseAndBuildLocalSchema(schemaRaw);
+        const dataJson = this.facade.getBaseProperty("dataJson");
+        const data = this.facade.getBaseProperty("data");
+
+        let hasSchema = !!schema;
+        if (hasSchema && isRecord(schema) && Object.keys(schema).length === 0) {
+            hasSchema = false;
+        }
+        const hasData = this.isDataNonEmpty(data, dataJson);
+
+        if (!hasSchema && !hasData) {
+            return null;
+        }
+
+        return this.createAndWireInnerHost(!hasSchema && hasData);
+    }
+
+    /**
+     * Initiates an asynchronous remote schema fetch for the given HTTP(S) URL.
+     * Uses a monotonic request token so superseded requests are safely discarded.
+     *
+     * @param url The remote schema URL to fetch.
+     */
+    public startRemoteFetch(url: string): void {
+        const reqId = ++this.fetchRequestId;
+        this.fetchUrl = url;
+        this.facade.setBusy(true);
+
+        this.fetchPromise = SchemaProvider.resolve(url)
+            .then((json) => {
+                if (reqId !== this.fetchRequestId || this.facade.isDestroyed()) {
+                    return;
+                }
+                this.facade.setBaseProperty("schemaDefinition", json, true);
+                this.facade.forwardResolvedSchemaToInnerHost(json);
+                this.facade.invalidate();
+            })
+            .catch((err: unknown) => {
+                if (reqId !== this.fetchRequestId || this.facade.isDestroyed()) {
+                    return;
+                }
+                Logger.error(`Failed to fetch remote schema: ${(err as Error).message}`, undefined, "DynamicHost");
+                MessageToast.show("Failed to fetch remote schema");
+                this.facade.setBaseProperty("schemaDefinition", null, true);
+                this.facade.invalidate();
+            })
+            .finally(() => {
+                if (reqId === this.fetchRequestId && !this.facade.isDestroyed()) {
+                    this.fetchPromise = null;
+                    this.fetchUrl = null;
+                    this.facade.setBusy(false);
+                }
+            });
+    }
+
+    private parseAndBuildLocalSchema(schemaRaw: unknown): unknown {
+        let schema: unknown = schemaRaw;
+        if (typeof schema === "string" && schema.trim().startsWith("{")) {
+            try {
+                schema = JSON.parse(schema);
+            } catch (e) {
+                Logger.warn(
+                    `Failed to parse JSON schema string in DynamicHost; delegating to SchemaNormalizer: ${(e as Error).message}`,
+                    undefined,
+                    "DynamicHost"
+                );
+            }
+        }
+
+        if (isRecord(schema)) {
+            type CustomBuilderLookup = {
+                getBuilderFor?: (
+                    s: Record<string, unknown>
+                ) => { build: (s: Record<string, unknown>, t?: string) => unknown } | undefined;
+            };
+            const customRegistry = this.facade.getBaseProperty("schemaBuilderRegistry") as CustomBuilderLookup | null;
+            const plugin = customRegistry?.getBuilderFor
+                ? customRegistry.getBuilderFor(schema)
+                : SchemaBuilderRegistry.getBuilderFor(schema);
+            if (plugin) {
+                const target = this.facade.getBaseProperty("schemaTarget") as string | undefined;
+                const built = plugin.build(schema, target) as { definitions?: unknown };
+                schema = built;
+            }
+        }
+        return schema;
+    }
+
+    private createAndWireInnerHost(isPureInference: boolean = false): GeneratorHost {
+        const innerHost = isPureInference ? new InferredGeneratorHost() : new GeneratorHost();
+        const props = this.facade.getMetadata().getProperties();
+        for (const propName of Object.keys(props)) {
+            if (propName === "width" || propName === "height") {
+                continue;
+            }
+            const val: unknown = this.facade.getBaseProperty(propName);
+            if (val !== null && val !== undefined) {
+                innerHost.setProperty(propName, val);
+            }
+        }
+
+        const events = this.facade.getMetadata().getEvents();
+        for (const eventName of Object.keys(events)) {
+            innerHost.attachEvent(eventName, (oEvent: Event) => {
+                if (eventName === "submit" || eventName === "fieldChange") {
+                    const params = oEvent.getParameters() as {
+                        payload?: Record<string, unknown>;
+                        payloadJson?: string;
+                    };
+                    if (params.payload) {
+                        const isLive = this.facade.getBaseProperty("liveUpdate") === true;
+                        if (eventName === "submit" || isLive) {
+                            DataSyncDelegate.commitDataPair(this.facade, params.payload, params.payloadJson);
+                        }
+                    }
+                }
+                if (eventName === "validationStateChanged") {
+                    const vParams = oEvent.getParameters() as { isValid?: boolean };
+                    if (typeof vParams.isValid === "boolean") {
+                        this.facade.setBaseProperty("isValid", vParams.isValid, true);
+                    }
+                }
+                const allowed = this.facade.fireEvent(eventName, oEvent.getParameters(), true);
+                if (allowed === false) {
+                    oEvent.preventDefault();
+                    const params = oEvent.getParameters() as { preventDefault?: () => void };
+                    if (typeof params.preventDefault === "function") {
+                        params.preventDefault();
+                    }
+                }
+            });
+        }
+
+        return innerHost;
+    }
+}