@procaaso/alphinity-ui-components 1.1.2 → 1.3.0

package/README.md

@@ -72,6 +72,17 @@ function HMIPanel() {
 - `npm test` - Run tests with Vitest
 - `npm run lint` - Lint code with ESLint
 - `npm run typecheck` - Type check with TypeScript
+- `npm run dev` - Run the demo playground on http://localhost:3010
+
+### Demo views
+
+The demo (`npm run dev`) mounts one of three views, selected by a `?demo=` query param:
+
+- `http://localhost:3010/` *(default)* - **Runtime**: full P&ID canvas with live telemetry, simulation, and device control/config panels
+- `http://localhost:3010/?demo=single-node` - **Single-node HMI mockup** over the full plant SVG layout
+- `http://localhost:3010/?demo=gallery` - **Component gallery** of individual widgets
+
+> The demo is served, not opened as a file — `demo-dist/index.html` references assets by absolute path and will be blank if opened via `file://`. Use `npm run dev`, or `npx vite preview --config vite.demo.config.ts` for the built version.
 
 ### Components
 

package/dist/index.cjs

@@ -36,6 +36,7 @@ __export(index_exports, {
   CardValue: () => CardValue,
   CircularGauge: () => CircularGauge,
   ControlPanel: () => ControlPanel,
+  DEFAULT_STATUS_COLORS: () => DEFAULT_STATUS_COLORS,
   DEFAULT_THRESHOLDS: () => DEFAULT_THRESHOLDS,
   DashboardCard: () => DashboardCard,
   DeviceConfigPanel: () => DeviceConfigPanel,
@@ -85,6 +86,7 @@ __export(index_exports, {
   overlayStyles: () => overlayStyles,
   registerSymbol: () => registerSymbol,
   registerSymbols: () => registerSymbols,
+  resolveStatusColor: () => resolveStatusColor,
   useDeviceConfigs: () => useDeviceConfigs,
   useDeviceControls: () => useDeviceControls,
   useDrag: () => useDrag,
@@ -578,11 +580,12 @@ var ControlPanel = ({
   secondSetpointValue,
   onSecondSetpointChange,
   modeConfigs = {},
-  defaultUnit = "Units",
+  defaultUnit,
   defaultLabel = "Setpoint",
-  defaultMin = 0,
-  defaultMax = 100,
-  defaultPrecision = 2,
+  defaultMin,
+  defaultMax,
+  defaultPrecision,
+  scaling,
   status = "normal",
   collapsed = false,
   onCollapseChange,
@@ -604,11 +607,11 @@ var ControlPanel = ({
     onCollapseChange?.(!newExpanded);
   };
   const currentModeConfig = modeConfigs[selectedMode] || {};
-  const currentUnit = currentModeConfig.unit || defaultUnit;
+  const currentUnit = currentModeConfig.unit || defaultUnit || scaling?.units || "Units";
   const currentLabel = currentModeConfig.label || defaultLabel;
-  const currentMin = currentModeConfig.min ?? defaultMin;
-  const currentMax = currentModeConfig.max ?? defaultMax;
-  const currentPrecision = currentModeConfig.precision ?? defaultPrecision;
+  const currentMin = currentModeConfig.min ?? defaultMin ?? scaling?.euLow ?? 0;
+  const currentMax = currentModeConfig.max ?? defaultMax ?? scaling?.euHigh ?? 100;
+  const currentPrecision = currentModeConfig.precision ?? defaultPrecision ?? scaling?.decimals ?? 2;
   const hasSecondSetpoint = currentModeConfig.hasSecondSetpoint || false;
   const baseClass = "ui-control-panel";
   const statusClass = status ? `ui-control-panel--${status}` : "";
@@ -996,6 +999,31 @@ var NodeControlsPanel = ({
 
 // src/components/DeviceControlPanel/DeviceControlPanel.tsx
 var import_react5 = require("react");
+
+// src/theme/statusColors.ts
+var DEFAULT_STATUS_COLORS = {
+  normal: { fill: "#888888", stroke: "#6b6b6b", bg: "#888888", text: "#ffffff", border: "#6b6b6b" },
+  warning: { fill: "#f59e0b", stroke: "#d97706", bg: "#FFD700", text: "#000000", border: "#d97706" },
+  alarm: { fill: "#ef4444", stroke: "#dc2626", bg: "#FF0000", text: "#ffffff", border: "#dc2626" },
+  fault: { fill: "#dc2626", stroke: "#b91c1c", bg: "#FF0000", text: "#ffffff", border: "#b91c1c" },
+  off: { fill: "#edeeef", stroke: "#000000", bg: "#666666", text: "#ffffff", border: "#4b5563" },
+  starting: { fill: "#90EE90", stroke: "#22c55e", bg: "#90EE90", text: "#000000", border: "#22c55e" },
+  stopping: { fill: "#FFD700", stroke: "#d97706", bg: "#FFD700", text: "#000000", border: "#d97706" }
+};
+var STATUS_ALIASES = {
+  running: "normal",
+  stopped: "off"
+};
+function resolveStatusColor(status, customMap) {
+  const raw = (status || "off").toLowerCase();
+  const key = STATUS_ALIASES[raw] ?? raw;
+  const defaults = DEFAULT_STATUS_COLORS[key] ?? DEFAULT_STATUS_COLORS.off;
+  const overrides = customMap?.[key];
+  if (!overrides) return defaults;
+  return { ...defaults, ...overrides };
+}
+
+// src/components/DeviceControlPanel/DeviceControlPanel.tsx
 var import_jsx_runtime8 = require("react/jsx-runtime");
 function DeviceControlPanel({
   binding,
@@ -1012,6 +1040,8 @@ function DeviceControlPanel({
   onParameterChange,
   onStart,
   onStop,
+  startPending = false,
+  stopPending = false,
   onCustomAction,
   onOpenConfig,
   showConfigButton = true,
@@ -1070,23 +1100,8 @@ function DeviceControlPanel({
   const textColor = binding.theme?.textColor || "#000000";
   const mutedTextColor = "#666666";
   const selectedColor = "#b4d0fe";
-  const statusColors = {
-    normal: binding.theme?.statusColors?.normal || "#888888",
-    // Gray (no alarm)
-    warning: binding.theme?.statusColors?.warning || "#FFD700",
-    // Yellow
-    alarm: binding.theme?.statusColors?.alarm || "#FF0000",
-    // Red
-    fault: binding.theme?.statusColors?.fault || "#FF0000",
-    // Red
-    off: binding.theme?.statusColors?.off || "#666666",
-    // Dark gray
-    starting: binding.theme?.statusColors?.starting || "#90EE90",
-    // Light green
-    stopping: binding.theme?.statusColors?.stopping || "#FFD700"
-    // Yellow
-  };
-  const statusColor = statusColors[binding.state.status || "normal"];
+  const statusEntry = resolveStatusColor(binding.state.status, binding.theme?.statusColors);
+  const statusColor = statusEntry.bg;
   const handleModeChange = (mode) => {
     onModeChange?.(mode);
   };
@@ -1373,7 +1388,10 @@ function DeviceControlPanel({
           /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)(
             "div",
             {
-              onClick: () => setShowModeModal(true),
+              onClick: () => {
+                setPendingMode(currentMode);
+                setShowModeModal(true);
+              },
               style: {
                 padding: "12px",
                 backgroundColor: surfaceColor,
@@ -1770,11 +1788,10 @@ function DeviceControlPanel({
           "button",
           {
             onClick: onStart,
-            disabled: binding.state.isRunning,
             style: {
               flex: 1,
               height: touchSize,
-              backgroundColor: binding.state.isRunning ? "#a3a3a3" : "#10b981",
+              backgroundColor: "#10b981",
               color: "#ffffff",
               border: "none",
               borderRadius: "6px",
@@ -1782,21 +1799,20 @@ function DeviceControlPanel({
               fontWeight: 700,
               fontFamily: "Arial, sans-serif",
               letterSpacing: "0.5px",
-              cursor: binding.state.isRunning ? "not-allowed" : "pointer",
-              opacity: binding.state.isRunning ? 0.5 : 1
+              cursor: "pointer",
+              opacity: 1
             },
-            children: "START"
+            children: startPending ? "STARTING\u2026" : "START"
           }
         ),
         activeCapabilities?.canStop && /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(
           "button",
           {
             onClick: onStop,
-            disabled: !binding.state.isRunning,
             style: {
               flex: 1,
               height: touchSize,
-              backgroundColor: !binding.state.isRunning ? "#a3a3a3" : "#ef4444",
+              backgroundColor: "#ef4444",
               color: "#ffffff",
               border: "none",
               borderRadius: "6px",
@@ -1804,10 +1820,10 @@ function DeviceControlPanel({
               fontWeight: 700,
               fontFamily: "Arial, sans-serif",
               letterSpacing: "0.5px",
-              cursor: !binding.state.isRunning ? "not-allowed" : "pointer",
-              opacity: !binding.state.isRunning ? 0.5 : 1
+              cursor: "pointer",
+              opacity: 1
             },
-            children: "STOP"
+            children: stopPending ? "STOPPING\u2026" : "STOP"
           }
         )
       ] }),
@@ -4113,7 +4129,8 @@ function NodeRenderer({
   onNodeDragStart,
   draggingNodeId,
   dragOffset = { x: 0, y: 0 },
-  enableDrag = false
+  enableDrag = false,
+  statusColorMap
 }) {
   return /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("g", { id: "layer-nodes", children: nodes2.filter((node) => node.visible !== false).map((node) => {
     const symbol = getSymbolDefinition(node.symbolId);
@@ -4172,24 +4189,9 @@ function NodeRenderer({
         `translate(${centerX}, ${centerY}) scale(${scaleX}, ${scaleY}) translate(${-centerX}, ${-centerY})`
       );
     }
-    const getStatusColor = (status) => {
-      switch (status) {
-        case "running":
-          return "#22c55e";
-        // Green
-        case "alarm":
-          return "#ef4444";
-        // Red
-        case "warning":
-          return "#f59e0b";
-        // Orange
-        case "stopped":
-        default:
-          return "#edeeef";
-      }
-    };
-    const fillColor = node.customColors?.fill ?? getStatusColor(node.status);
-    const strokeColor = node.customColors?.stroke ?? "rgb(0, 0, 0)";
+    const statusEntry = resolveStatusColor(node.status, statusColorMap);
+    const fillColor = node.customColors?.fill ?? statusEntry.fill;
+    const strokeColor = node.customColors?.stroke ?? statusEntry.stroke;
     return /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)(
       "g",
       {
@@ -4453,14 +4455,16 @@ function DataOverlay({
   x,
   y,
   telemetry,
-  scale = 1
+  scale = 1,
+  statusColorMap
 }) {
-  const { value, display, history } = telemetry;
+  const { value, display, history, scaling } = telemetry;
   const showValue = display?.showValue ?? true;
   const showStatus = display?.showStatus ?? true;
   const showSparkline = display?.showSparkline ?? false;
   const label = display?.label;
-  const precision = display?.precision;
+  const precision = scaling?.decimals ?? display?.precision;
+  const unit = scaling?.units ?? value.unit;
   const sparklineColor = display?.sparklineColor;
   const textColor = display?.textColor;
   const backgroundColor = display?.backgroundColor;
@@ -4478,25 +4482,13 @@ function DataOverlay({
     }
     return val.toString();
   };
-  const defaultStatusColors = {
-    normal: { bg: "#10b981", text: "#ffffff", border: "#059669" },
-    warning: { bg: "#f59e0b", text: "#ffffff", border: "#d97706" },
-    alarm: { bg: "#ef4444", text: "#ffffff", border: "#dc2626" },
-    fault: { bg: "#dc2626", text: "#ffffff", border: "#b91c1c" },
-    off: { bg: "#6b7280", text: "#ffffff", border: "#4b5563" }
-  };
-  const getStatusColors = () => {
-    const customColor = telemetry.statusColors?.[value.status];
-    if (customColor) {
-      return { bg: customColor, text: "#ffffff", border: customColor };
-    }
-    return defaultStatusColors[value.status] || defaultStatusColors.normal;
-  };
-  const statusColors = getStatusColors();
+  const resolvedEntry = resolveStatusColor(value.status, statusColorMap);
+  const customColor = telemetry.statusColors?.[value.status];
+  const statusColors = customColor ? { bg: customColor, text: "#ffffff", border: customColor } : { bg: resolvedEntry.bg, text: resolvedEntry.text, border: resolvedEntry.border };
   const colors = backgroundColor && backgroundColor !== "status" ? { bg: backgroundColor, text: textColor || "#ffffff", border: backgroundColor } : statusColors;
   const finalTextColor = textColor || colors.text;
   const formattedValue = formatValue(value.value);
-  const displayText = value.unit ? `${formattedValue} ${value.unit}` : formattedValue;
+  const displayText = unit ? `${formattedValue} ${unit}` : formattedValue;
   const sparklinePath = (() => {
     if (!showSparkline || !history || history.length < 2) return "";
     const width = 70 * scale;
@@ -4504,8 +4496,9 @@ function DataOverlay({
     const padding = 5 * scale;
     const effectiveWidth = width - padding * 2;
     const effectiveHeight = height - padding * 2;
-    const min = Math.min(...history);
-    const max = Math.max(...history);
+    const hasEuRange = scaling?.euLow !== void 0 && scaling?.euHigh !== void 0 && scaling.euHigh !== scaling.euLow;
+    const min = hasEuRange ? scaling.euLow : Math.min(...history);
+    const max = hasEuRange ? scaling.euHigh : Math.max(...history);
     const range = max - min || 1;
     const points = history.map((val, i) => {
       const xPos = i / (history.length - 1) * effectiveWidth + padding;
@@ -5763,6 +5756,7 @@ function PIDCanvas({
   onPipeCreated,
   onMounted,
   telemetry,
+  statusColorMap,
   ...props
 }) {
   const [localDiagram, setLocalDiagram] = (0, import_react16.useState)(diagram);
@@ -6416,7 +6410,8 @@ function PIDCanvas({
                   enableDrag: dragEnabled && !isConnecting,
                   onNodeDragStart: dragEnabled && !isConnecting ? handleNodeDragStart : void 0,
                   draggingNodeId: dragState.draggedId,
-                  dragOffset: dragState.offset
+                  dragOffset: dragState.offset,
+                  statusColorMap
                 }
               ),
               (features.editPipeRoutes ?? false) && /* @__PURE__ */ (0, import_jsx_runtime19.jsx)(
@@ -6450,7 +6445,8 @@ function PIDCanvas({
                     x: overlayX,
                     y: overlayY,
                     telemetry: binding,
-                    scale: features.telemetryScale ?? 1
+                    scale: features.telemetryScale ?? 1,
+                    statusColorMap
                   },
                   `telemetry-${node.id}`
                 );
@@ -7664,7 +7660,11 @@ function createControlBinding(nodeId, deviceConfig, actions) {
 
 // src/hooks/useDeviceControls.ts
 var import_react18 = require("react");
-function useDeviceControls(initialBindings) {
+function commandKey(nodeId, kind, suffix) {
+  return suffix ? `${nodeId}:${kind}:${suffix}` : `${nodeId}:${kind}`;
+}
+function useDeviceControls(initialBindings, options) {
+  const { commandTimeoutMs } = options ?? {};
   const [controls, setControls] = (0, import_react18.useState)(() => {
     const map = /* @__PURE__ */ new Map();
     if (initialBindings) {
@@ -7674,6 +7674,11 @@ function useDeviceControls(initialBindings) {
     }
     return map;
   });
+  const pendingRef = (0, import_react18.useRef)(/* @__PURE__ */ new Map());
+  const [pendingCommands, setPendingCommands] = (0, import_react18.useState)(() => /* @__PURE__ */ new Set());
+  const syncPending = (0, import_react18.useCallback)(() => {
+    setPendingCommands(new Set(pendingRef.current.keys()));
+  }, []);
   const updateControl = (0, import_react18.useCallback)((nodeId, updates) => {
     setControls((prev) => {
       const newMap = new Map(prev);
@@ -7763,121 +7768,112 @@ function useDeviceControls(initialBindings) {
     },
     [controls]
   );
-  const sendModeChange = (0, import_react18.useCallback)(
-    async (nodeId, mode) => {
-      const binding = controls.get(nodeId);
-      if (!binding) return;
-      updateDeviceState(nodeId, { currentMode: mode });
-      try {
-        await binding.actions.onModeChange?.(mode);
-        updateDeviceState(nodeId, {
-          lastCommandTime: Date.now(),
-          lastCommandResult: { success: true, message: `Mode changed to ${mode}` }
-        });
-      } catch (error) {
-        updateDeviceState(nodeId, {
-          currentMode: binding.state.currentMode,
-          lastCommandResult: {
-            success: false,
-            message: error instanceof Error ? error.message : "Mode change failed"
-          }
-        });
+  const isCommandPending = (0, import_react18.useCallback)(
+    (nodeId, kind) => {
+      if (kind) {
+        const prefix2 = `${nodeId}:${kind}`;
+        for (const key of pendingCommands) {
+          if (key === prefix2 || key.startsWith(`${prefix2}:`)) return true;
+        }
+        return false;
       }
+      const prefix = `${nodeId}:`;
+      for (const key of pendingCommands) {
+        if (key.startsWith(prefix)) return true;
+      }
+      return false;
     },
-    [controls, updateDeviceState]
+    [pendingCommands]
   );
-  const sendParameterChange = (0, import_react18.useCallback)(
-    async (nodeId, parameterId, value) => {
-      const binding = controls.get(nodeId);
-      if (!binding) return;
-      updateParameter(nodeId, parameterId, value);
-      try {
-        await binding.actions.onParameterChange?.(parameterId, value);
-        updateDeviceState(nodeId, {
-          lastCommandTime: Date.now(),
-          lastCommandResult: { success: true, message: `Parameter ${parameterId} updated` }
-        });
-      } catch (error) {
-        updateDeviceState(nodeId, {
-          lastCommandResult: {
-            success: false,
-            message: error instanceof Error ? error.message : "Parameter change failed"
-          }
-        });
-      }
+  const markPending = (0, import_react18.useCallback)(
+    (key, delta) => {
+      const next = (pendingRef.current.get(key) ?? 0) + delta;
+      if (next > 0) pendingRef.current.set(key, next);
+      else pendingRef.current.delete(key);
+      syncPending();
     },
-    [controls, updateParameter, updateDeviceState]
+    [syncPending]
   );
-  const sendStartCommand = (0, import_react18.useCallback)(
-    async (nodeId) => {
+  const runCommand = (0, import_react18.useCallback)(
+    async (nodeId, key, invoke, messages) => {
       const binding = controls.get(nodeId);
       if (!binding) return;
-      updateDeviceState(nodeId, { isRunning: true, status: "starting" });
+      markPending(key, 1);
+      let timer;
       try {
-        await binding.actions.onStart?.();
+        const action = Promise.resolve(invoke(binding));
+        if (commandTimeoutMs && commandTimeoutMs > 0) {
+          await Promise.race([
+            action,
+            new Promise((_, reject) => {
+              timer = setTimeout(
+                () => reject(new Error(`${messages.success.replace(/ sent$/, "")} timed out (unconfirmed)`)),
+                commandTimeoutMs
+              );
+            })
+          ]);
+        } else {
+          await action;
+        }
         updateDeviceState(nodeId, {
-          status: "normal",
           lastCommandTime: Date.now(),
-          lastCommandResult: { success: true, message: "Device started" }
+          lastCommandResult: { success: true, message: messages.success }
         });
       } catch (error) {
         updateDeviceState(nodeId, {
-          isRunning: false,
-          status: "fault",
+          lastCommandTime: Date.now(),
           lastCommandResult: {
             success: false,
-            message: error instanceof Error ? error.message : "Start failed"
+            message: error instanceof Error ? error.message : messages.failure
           }
         });
+      } finally {
+        if (timer) clearTimeout(timer);
+        markPending(key, -1);
       }
     },
-    [controls, updateDeviceState]
+    [controls, updateDeviceState, markPending, commandTimeoutMs]
+  );
+  const sendModeChange = (0, import_react18.useCallback)(
+    (nodeId, mode) => runCommand(
+      nodeId,
+      commandKey(nodeId, "mode"),
+      (binding) => binding.actions.onModeChange?.(mode),
+      { success: `Mode ${mode} command sent`, failure: "Mode change failed" }
+    ),
+    [runCommand]
+  );
+  const sendParameterChange = (0, import_react18.useCallback)(
+    (nodeId, parameterId, value) => runCommand(
+      nodeId,
+      commandKey(nodeId, "parameter", parameterId),
+      (binding) => binding.actions.onParameterChange?.(parameterId, value),
+      { success: `Parameter ${parameterId} command sent`, failure: "Parameter change failed" }
+    ),
+    [runCommand]
+  );
+  const sendStartCommand = (0, import_react18.useCallback)(
+    (nodeId) => runCommand(nodeId, commandKey(nodeId, "start"), (binding) => binding.actions.onStart?.(), {
+      success: "Start command sent",
+      failure: "Start command failed"
+    }),
+    [runCommand]
   );
   const sendStopCommand = (0, import_react18.useCallback)(
-    async (nodeId) => {
-      const binding = controls.get(nodeId);
-      if (!binding) return;
-      updateDeviceState(nodeId, { isRunning: false, status: "stopping" });
-      try {
-        await binding.actions.onStop?.();
-        updateDeviceState(nodeId, {
-          status: "off",
-          lastCommandTime: Date.now(),
-          lastCommandResult: { success: true, message: "Device stopped" }
-        });
-      } catch (error) {
-        updateDeviceState(nodeId, {
-          isRunning: true,
-          status: "fault",
-          lastCommandResult: {
-            success: false,
-            message: error instanceof Error ? error.message : "Stop failed"
-          }
-        });
-      }
-    },
-    [controls, updateDeviceState]
+    (nodeId) => runCommand(nodeId, commandKey(nodeId, "stop"), (binding) => binding.actions.onStop?.(), {
+      success: "Stop command sent",
+      failure: "Stop command failed"
+    }),
+    [runCommand]
   );
   const sendCustomAction = (0, import_react18.useCallback)(
-    async (nodeId, actionId) => {
-      const binding = controls.get(nodeId);
-      if (!binding) return;
-      try {
-        await binding.actions.onCustomAction?.(actionId);
-        updateDeviceState(nodeId, {
-          lastCommandTime: Date.now(),
-          lastCommandResult: { success: true, message: `Action ${actionId} executed` }
-        });
-      } catch (error) {
-        updateDeviceState(nodeId, {
-          lastCommandResult: {
-            success: false,
-            message: error instanceof Error ? error.message : "Action failed"
-          }
-        });
-      }
-    },
-    [controls, updateDeviceState]
+    (nodeId, actionId) => runCommand(
+      nodeId,
+      commandKey(nodeId, "action", actionId),
+      (binding) => binding.actions.onCustomAction?.(actionId),
+      { success: `Action ${actionId} command sent`, failure: "Action failed" }
+    ),
+    [runCommand]
   );
   return {
     controls,
@@ -7888,6 +7884,10 @@ function useDeviceControls(initialBindings) {
     setControlBinding,
     removeControlBinding,
     getControlBinding,
+    // In-flight command visibility (interaction state, not device state).
+    // `isCommandPending` is the stable query surface; the raw key set is
+    // intentionally not exported (its key format is an implementation detail).
+    isCommandPending,
     // Command helpers
     sendModeChange,
     sendParameterChange,
@@ -8946,6 +8946,7 @@ function useSimulation(telemetry, updateTelemetryBatch, options = {}) {
   CardValue,
   CircularGauge,
   ControlPanel,
+  DEFAULT_STATUS_COLORS,
   DEFAULT_THRESHOLDS,
   DashboardCard,
   DeviceConfigPanel,
@@ -8995,6 +8996,7 @@ function useSimulation(telemetry, updateTelemetryBatch, options = {}) {
   overlayStyles,
   registerSymbol,
   registerSymbols,
+  resolveStatusColor,
   useDeviceConfigs,
   useDeviceControls,
   useDrag,