@adcops/autocore-react 3.0.40 → 3.3.2

package/src/core/AutoCoreTagContext.tsx

@@ -0,0 +1,615 @@
+/*
+ * Copyright (C) 2025 Automated Design Corp.. All Rights Reserved.
+ * Created Date: 2025-09-05 07:35:46
+ * -----
+ * Last Modified: 2026-01-29 09:31:42
+ * Modified By: ADC
+ * -----
+ *
+ */
+
+/**
+ * @module core/AutoCoreTagContext
+ * 
+ * @document ../../additional-docs/AutCoreTagContext.md
+ *
+ * @summary
+ * A React Context + Provider that manages the state and synchronization of "Tags" (data points)
+ * between the React frontend and the AutoCore backend.
+ * 
+ * It acts as the central data store for real-time values, handling:
+ * - **Buffering**: Stores raw controller values exactly as received.
+ * - **Scaling**: Converts raw values to display values (e.g., mm -> inches) based on configuration.
+ * - **Synchronization**: Subscribes to live updates from the server.
+ * - **Writing**: Converts display values back to raw controller units before sending.
+ *
+ * @remarks
+ * ❖ **Dual-State Representation**
+ * To prevent rounding errors and race conditions, we maintain two parallel states:
+ * 1. `rawValues[tagName]`: The exact value received from the controller (Source of Truth).
+ * 2. `values[tagName]`: The derived value shown in the UI (calculated from raw + scale).
+ * 
+ * When a scale changes (e.g., user switches units), we recompute `values` from `rawValues`.
+ * We *never* rescale a previously scaled value.
+ *
+ * ❖ **Key Features**
+ * - **Resilient Initialization**: Eagerly fetches initial values (via ADS refresh or read fallback).
+ * - **Server-Stored Scales**: Can load unit preferences from the server (GNV domain).
+ * - **Optimized Updates**: Uses stable references and memoization to minimize React re-renders.
+ * - **Type Safety**: Strongly typed context via generic `VMapRuntime`.
+ *
+ * @example Minimal wiring
+ * ```tsx
+ * // 1. Define your tags
+ * const tags = [
+ *   { tagName: "position", fqdn: "ADS.Axis.Pos", valueType: "number", scale: "dist" },
+ *   { tagName: "speed",    fqdn: "ADS.Axis.Vel", valueType: "number", scale: "dist" }
+ * ];
+ * 
+ * // 2. Define scales
+ * const scales = {
+ *   dist: { name: "dist", scale: 1.0, label: "mm" }
+ * };
+ * 
+ * // 3. Wrap application
+ * <AutoCoreTagProvider tags={tags} scales={scales}>
+ *   <App />
+ * </AutoCoreTagProvider>
+ * ```
+ */
+
+import React, {
+    useRef,
+    createContext,
+    useCallback,
+    useContext,
+    useEffect,
+    useMemo,
+    useState,
+    type ReactNode,
+} from "react";
+import { EventEmitterContext } from "./EventEmitterContext";
+import type {
+    BaseContextValue,
+    TagConfig,
+    ScaleConfig
+} from "./AutoCoreTagTypes";
+
+import { MessageType } from "../hub/CommandMessage";
+
+/**
+ * Runtime type for the values map - allows any tag name to map to any value type.
+ * This is the generic type used when the specific tag configuration is not known at compile time.
+ */
+type VMapRuntime = Record<string, unknown>;
+
+/**
+ * The React Context that holds all AutoCore tag state and operations.
+ *
+ * This context provides:
+ * - `values`: Display values (with scaling/codecs applied)
+ * - `rawValues`: Raw controller values as received from server
+ * - `isLoading`: Whether initial data loading is complete
+ * - `write`: Function to write a value to a tag
+ * - `tap`: Function to pulse a boolean tag (true → delay → false)
+ * - `scales`: Current scale configurations
+ * - `updateScale`: Function to change a scale factor/label
+ *
+ * @see AutoCoreTagProvider for the provider implementation
+ * @see makeAutoCoreTagHooks for creating typed hooks from this context
+ */
+export const AutoCoreTagContext = createContext<BaseContextValue<VMapRuntime>>({
+    values: {},
+    rawValues: {},
+    isLoading: true,
+    write: async () => { },
+    tap: async () => { },
+    scales: {},
+    updateScale: async () => { },
+});
+
+/**
+ * Standard response envelope from the AutoCore server.
+ * All server responses follow this structure.
+ *
+ * @template T - The type of data contained in the response
+ * @property success - Whether the operation succeeded
+ * @property valid - Whether the response data is valid
+ * @property data - The actual response payload
+ */
+type HubEnvelope<T> = { success?: boolean; valid?: boolean; data?: T };
+
+/**
+ * Utility function to create a promise that resolves after a specified delay.
+ * Used for tap() pulse timing and retry delays.
+ *
+ * @param ms - Number of milliseconds to sleep
+ * @returns Promise that resolves after the delay
+ */
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Extracts the domain (first segment) from a Fully-Qualified Domain Name.
+ * @param fqdn - The full topic path (e.g., "ads.plc1.gio.bControlPowerOk")
+ * @returns The domain segment (e.g., "ads")
+ */
+
+
+
+/**
+ * AutoCoreTagProvider
+ *
+ * @description
+ * React Provider that wires up AutoCore tags to live server updates, buffers **raw**
+ * controller values, exposes **display** values (scales/codec applied), and handles
+ * writes/taps with proper domain envelopes. Scaling is **always** applied to display
+ * values only; raw values remain untouched and are the single source of truth.
+ *
+ * @param props.tags - List of tag configurations (tagName, fqdn, etc.)
+ * @param props.scales - Map of scale definitions (name, factor, label)
+ * @param props.eagerRead - If true, automatically fetches initial values on mount
+ */
+export const AutoCoreTagProvider: React.FC<{
+    children: ReactNode;
+    tags: readonly TagConfig[];
+    scales?: Record<string, ScaleConfig>;
+    eagerRead?: boolean;
+}> = ({ children, tags, scales, eagerRead = true }) => {
+    const startedRef = useRef(false);
+
+    // PERFORMANCE: Memoize default scales to ensure reference stability.
+    // If 'scales' prop is undefined, we use this stable empty object.
+    // This prevents infinite re-render loops caused by creating a new object on every render.
+    const defaultScales = useMemo<Record<string, ScaleConfig>>(() => ({}), []);
+    const actualScales: Record<string, ScaleConfig> = scales ?? defaultScales;
+
+    const { invoke, read, write: hubWrite, serverSubscribe, isConnected, subscribe, unsubscribe } =
+        useContext(EventEmitterContext);
+
+    /** 
+     * Raw (controller) values as received from the server (pre-scale, pre-codec). 
+     * This is the single source of truth for value data.
+     * Seeded with `initialValue` from tag config if available.
+     * Keyed by `tagName`.
+     */
+    const [rawValues, setRawValues] = useState<Record<string, unknown>>(() => {
+        const seed: Record<string, unknown> = {};
+        for (const t of tags) {
+            if (t.initialValue !== undefined) {
+                // Interpret initialValue as **raw**.
+                seed[t.tagName] = t.initialValue;
+            }
+        }
+        return seed;
+    });
+
+    /** 
+     * App-visible display values, computed from raw using scales/codecs.
+     * This is what the UI consumes.
+     * Keyed by `tagName`.
+     */
+    const [values, setValues] = useState<Record<string, unknown>>({});
+
+    /** 
+     * Current state of scales (factor/label).
+     * Can be updated by the server or user interaction.
+     */
+    const [scaleValues, setScaleValues] =
+        useState<Record<string, ScaleConfig>>(actualScales);
+
+    /** 
+     * Refs to access latest state inside callbacks without adding them to dependency arrays.
+     * This helps prevent re-subscribing when state changes.
+     */
+    const scaleRef = useRef(scaleValues);
+    const rawRef = useRef(rawValues);
+    useEffect(() => { scaleRef.current = scaleValues; }, [scaleValues]);
+    useEffect(() => { rawRef.current = rawValues; }, [rawValues]);
+
+    const [isLoading, setIsLoading] = useState(true);
+
+    /**
+     * Converts a raw controller value to a display value.
+     *
+     * Pipeline: Raw -> [Codec Decode] -> [Scale Multiply] -> Display
+     */
+    const toDisplay = useCallback((tag: TagConfig, raw: unknown): unknown => {
+        const { valueType, scale, codec } = tag;
+
+        // 1) numeric scaling: multiply raw by scale factor
+        if (valueType === "number" && typeof raw === "number" && scale) {
+            const s = scaleRef.current[scale];
+            const factor = s?.scale ?? 1;
+            return raw * factor;
+        }
+
+        // 2) codec for json (optional): decode server representation
+        if (valueType === "json" && codec?.fromServer) {
+            try { return codec.fromServer(raw); } catch { /* fall through */ }
+        }
+
+        // 3) pass-through: no transformation needed
+        return raw;
+    }, []);
+
+    /**
+     * Converts a display value back to a raw controller value.
+     *
+     * Pipeline: Display -> [Scale Divide] -> [Codec Encode] -> Raw
+     */
+    const toServer = useCallback((tag: TagConfig, display: unknown): unknown => {
+        const { valueType, scale, codec } = tag;
+
+        // 1) invert codec first (json): encode for server
+        if (valueType === "json" && codec?.toServer) {
+            try { display = codec.toServer(display as any); } catch { /* fall through */ }
+        }
+
+        // 2) inverse numeric scaling: divide by scale factor
+        if (valueType === "number" && typeof display === "number" && scale) {
+            const s = scaleRef.current[scale];
+            const factor = s?.scale ?? 1;
+            return display / factor;
+        }
+
+        return display;
+    }, []);
+
+    /**
+     * Recomputes display values for all tags in a specific scale group.
+     * Called when a scale factor changes.
+     * 
+     * CRITICAL: Computes from `rawValues` (Source of Truth), not existing `values`.
+     * This prevents floating point error accumulation from repeated scaling.
+     */
+    const rescaleFromRaw = useCallback((scaleName: string) => {
+        const affected = tags.filter(t => t.scale === scaleName);
+        if (!affected.length) return;
+
+        setValues(prev => {
+            const next = { ...prev };
+            for (const tag of affected) {
+                const raw = rawRef.current[tag.tagName];
+                if (typeof raw !== "number") continue;
+                const disp = toDisplay(tag, raw);
+                if (next[tag.tagName] !== disp) next[tag.tagName] = disp;
+            }
+            return next;
+        });
+    }, [tags, toDisplay]);
+
+    /**
+     * Handles incoming value updates from the server.
+     * 
+     * 1. Updates `rawValues` (Source of Truth).
+     * 2. Computes and updates `values` (Display).
+     * 3. Uses functional state updates to ensure atomicity.
+     * 4. Keys by `tagName` for consistent access by hooks.
+     */
+    const handleTagUpdate = useCallback((tag: TagConfig, raw: unknown) => {
+        // Store the raw controller value (source of truth for scaling)
+        setRawValues(prev =>
+            prev[tag.tagName] === raw ? prev : { ...prev, [tag.tagName]: raw }
+        );
+        // Compute and store the display value (with scaling/codecs applied)
+        const display = toDisplay(tag, raw);
+        setValues(prev =>
+            prev[tag.tagName] === display ? prev : { ...prev, [tag.tagName]: display }
+        );
+    }, [toDisplay]);
+
+    /**
+     * Eagerly fetches initial values for non-ADS domains (e.g., MODBUS).
+     * Uses a worker pool to fetch in parallel while respecting rate limits.
+     */
+    const eagerPullNonADS = useCallback(
+        async (
+            domain: string,
+            tagList: readonly TagConfig[],
+            opts?: { concurrency?: number; minDelayMs?: number; jitterMs?: number }
+        ) => {
+            const concurrency = opts?.concurrency ?? 4;
+            const minDelayMs = opts?.minDelayMs ?? 20;
+            const jitterMs = opts?.jitterMs ?? 40;
+
+            let index = 0;
+
+            const workers = Array.from({ length: concurrency }, () => (async () => {
+                while (true) {
+                    const i = index++;
+                    if (i >= tagList.length) return;
+                    const tag = tagList[i];
+
+                    try {
+                        // Try 'refresh' first (server broadcast), else 'read_value'
+                        let usedPublishPath = false;
+                        try {
+                            await invoke(tag.fqdn, MessageType.Request, { action: "refresh" });
+                            usedPublishPath = true;
+                        } catch { /* fall through */ }
+
+                        if (!usedPublishPath) {
+                            const payload = domain.toUpperCase() === "GNV" ? { group: "ux" } : {};
+                            try {
+                                const resp: any = await read(tag.fqdn, payload);
+                                if (resp?.success) {
+                                    handleTagUpdate(tag, resp.data);
+                                }
+                            } catch (err) { /* ignore missing keys on init */ }
+                        }
+                    } catch (outerErr) { /* ignore */ } 
+                    finally {
+                        const extra = Math.floor(Math.random() * jitterMs);
+                        await sleep(minDelayMs + extra);
+                    }
+                }
+            })());
+
+            await Promise.all(workers);
+        },
+        [invoke, read, handleTagUpdate]
+    );
+
+    /**
+     * Reads scale configurations from the server (if configured).
+     * Ensures display units match the server's persisted configuration.
+     */
+    const pullServerScales = useCallback(async () => {
+        // Use actualScales to ensure we iterate over a stable object
+        for (const [scaleName, cfg] of Object.entries(actualScales)) {
+            if (!cfg.serverTag) continue;
+            const { domain, symbolName } = cfg.serverTag;
+
+            try {
+                const respUnknown = await read(`${domain}.${symbolName}`, { group: "ux" });
+                const env = respUnknown as HubEnvelope<string>;
+                
+                if (env.data && (env.success ?? true) && (env.valid ?? true)) {
+                    const env_data = JSON.parse(env.data) as ScaleConfig;
+                    if (env_data && typeof env_data.scale === "number" ) {
+                        const { scale, label } = env_data;
+                        setScaleValues(prev => ({
+                            ...prev,
+                            [scaleName]: {
+                                ...prev[scaleName],
+                                scale,
+                                label: label ?? prev[scaleName]?.label ?? "---",
+                            },
+                        }));
+                        rescaleFromRaw(scaleName);
+                    }
+                }
+            } catch { /* Scale not present, use default */ }
+        }
+    }, [read, actualScales, rescaleFromRaw]);
+
+    /**
+     * ==========================================================================
+     * MAIN SUBSCRIPTION WIRING EFFECT
+     * ==========================================================================
+     * Orchestrates the initialization sequence:
+     * 1. Load server scales.
+     * 2. Subscribe to tags (Server & Local).
+     * 3. Perform one-shot reads (ADS refresh).
+     */
+    useEffect(() => {
+        let mounted = true;
+        const subscriptions: number[] = [];
+
+        const registerAndSubscribe = async () => {
+            try {
+                // 1. Load scales first so initial values are correct
+                await pullServerScales();
+
+                // 2. Subscribe to all tags
+                for (const tag of tags) {
+                    console.log(`Subscribe on [${tag.tagName}]  ${tag.fqdn}  ...`);
+                    
+                    // A. Server Subscription: Tell backend to start sending updates.
+                    //    We pass tagName so the Hub can map the FQDN back to the local name.
+                    await serverSubscribe(tag.tagName, tag.fqdn, tag.subscriptionOptions);
+
+                    // B. Local Subscription: Listen for updates on the Event Bus.
+                    //    The Hub will receive FQDN messages, map them to tagName, and dispatch.
+                    const id = subscribe(tag.tagName, (data) => {
+                        if (!mounted) return;
+                        // data is the raw value payload directly
+                        handleTagUpdate(tag, data);
+                    });
+                    subscriptions.push(id);
+                }
+
+                // // 3. ADS Refresh: Ask ADS to broadcast current values immediately.
+                // if (eagerRead) {
+                //     await invoke("ADS.refresh", MessageType.Request, {});
+                // }
+                
+            } finally {
+                if (mounted) setTimeout(() => mounted && setIsLoading(false), 100);
+            }
+        };
+
+        // Prevents double-execution in React Strict Mode
+        const safeRegister = async () => {
+            if (!mounted || startedRef.current) return;
+            startedRef.current = true;
+            try { await registerAndSubscribe(); }
+            finally { if (mounted) setTimeout(() => mounted && setIsLoading(false), 100); }
+        };
+
+        // Wait for connection before registering
+        if (!isConnected()) {
+            const id = subscribe("HUB/connected", () => {
+                unsubscribe(id);
+                void safeRegister();
+            });
+            subscriptions.push(id);
+        } else {
+            void safeRegister();
+        }
+
+        return () => {
+            mounted = false;
+            subscriptions.forEach(unsubscribe);
+            startedRef.current = false;
+        };
+    }, [subscribe, unsubscribe, isConnected, invoke, serverSubscribe, eagerRead, tags, pullServerScales, eagerPullNonADS, handleTagUpdate]);
+
+    /**
+     * Memoized list of scales that need server subscriptions.
+     * Used for the separate effect that listens for live scale changes.
+     */
+    const scaleServerSubs = useMemo(
+        () =>
+            Object.entries(actualScales)
+                .filter(([, cfg]) => cfg.serverTag)
+                .map(([scaleName, cfg]) => ({
+                    scaleName,
+                    domain: cfg.serverTag!.domain,
+                    symbolName: cfg.serverTag!.symbolName,
+                })),
+        [actualScales]
+    );
+
+    /**
+     * Effect to listen for live scale changes from the server.
+     * If another user changes units, this updates our local state immediately.
+     */
+    useEffect(() => {
+        let mounted = true;
+        const subs: number[] = [];
+
+        for (const { scaleName, domain, symbolName } of scaleServerSubs) {
+            const id = subscribe(`${domain}.${symbolName}`, (data) => {
+                if (!mounted) return;
+                const v = data?.value; // Scales come as { value: { scale, label } } usually
+                if (v && typeof v === "object" && typeof (v as any).scale === "number") {
+                    const { scale, label } = v as { scale: number; label?: string };
+                    setScaleValues(prev => ({
+                        ...prev,
+                        [scaleName]: {
+                            ...prev[scaleName],
+                            scale,
+                            label: label ?? prev[scaleName]?.label ?? "---",
+                        },
+                    }));
+                    rescaleFromRaw(scaleName);
+                }
+            });
+            subs.push(id);
+        }
+
+        return () => {
+            mounted = false;
+            subs.forEach(unsubscribe);
+        };
+    }, [subscribe, unsubscribe, scaleServerSubs, rescaleFromRaw]);
+
+    /**
+     * Writes a value to the server.
+     * 1. Finds tag config by `tagName`.
+     * 2. Inverse-scales the value (Display -> Raw).
+     * 3. Sends update to server using `fqdn`.
+     */
+    const write = useCallback(
+        async (tagName: string, displayValue: unknown) => {
+            const cfg = tags.find((t) => t.tagName === tagName);
+            if (!cfg) {
+                console.error(`write(): unknown tag '${tagName}'`);
+                return;
+            }
+
+            const serverValue = toServer(cfg, displayValue);
+            await hubWrite(cfg.fqdn, serverValue);
+        },
+        [tags, hubWrite, toServer]
+    );
+
+    /**
+     * Momentary pulse for boolean tags (True -> Wait 300ms -> False).
+     */
+    const tap = useCallback(
+        async (tagName: string) => {
+            const cfg = tags.find((t) => t.tagName === tagName);
+            if (!cfg) {
+                console.error(`tap(): unknown tag '${tagName}'`);
+                return;
+            }
+            if (cfg.valueType !== "boolean") {
+                console.warn(`tap(): tag '${tagName}' is not a boolean type`);
+                return;
+            }
+
+            await hubWrite(cfg.fqdn, true);
+            await sleep(300);
+            await hubWrite(cfg.fqdn, false);
+        },
+        [tags, hubWrite]
+    );
+
+    /**
+     * Updates a scale factor locally and optionally persists to server.
+     */
+    const updateScale = useCallback(
+        async (scaleName: string, newScale: number, newLabel: string) => {
+            const cfg = scaleValues[scaleName];
+            if (!cfg) {
+                console.error(`Scale '${scaleName}' not found`);
+                return;
+            }
+
+            if (cfg.serverTag) {
+                const topic = `${cfg.serverTag.domain}.${cfg.serverTag.symbolName}`;
+                await hubWrite(topic, { name: scaleName, scale: newScale, label: newLabel });
+            }
+
+            setScaleValues(prev => ({
+                ...prev,
+                [scaleName]: { ...prev[scaleName], scale: newScale, label: newLabel },
+            }));
+
+            rescaleFromRaw(scaleName);
+        },
+        [scaleValues, hubWrite, rescaleFromRaw]
+    );
+
+    /**
+     * Safety net: Recomputes all display values whenever scales or tags change.
+     * Ensures UI consistency even if individual updates were missed.
+     */
+    useEffect(() => {
+        setValues(prev => {
+            const next = { ...prev };
+            for (const tag of tags) {
+                const raw = rawRef.current[tag.tagName];
+                if (raw === undefined) continue;
+                const disp = toDisplay(tag, raw);
+                if (next[tag.tagName] !== disp) next[tag.tagName] = disp;
+            }
+            return next;
+        });
+    }, [tags, toDisplay, scaleValues]);
+
+    /**
+     * Construct context value. Memoized to prevent consumers from re-rendering
+     * unless actual data changes.
+     */
+    const ctxValue = useMemo<BaseContextValue<VMapRuntime>>(
+        () => ({
+            values,       // Display values (scaled)
+            rawValues,    // Raw values (unscaled)
+            isLoading,
+            write,
+            tap,
+            scales: scaleValues,
+            updateScale,
+        }),
+        [values, rawValues, isLoading, write, tap, scaleValues, updateScale]
+    );
+
+    return (
+        <AutoCoreTagContext.Provider value={ctxValue}>
+            {children}
+        </AutoCoreTagContext.Provider>
+    );
+};