@procaaso/alphinity-ui-components 1.1.3 → 1.4.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

@@ -580,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,
@@ -606,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}` : "";
@@ -1037,8 +1038,11 @@ function DeviceControlPanel({
   toastDuration = 3e3,
   onModeChange,
   onParameterChange,
+  onParameterActivate,
   onStart,
   onStop,
+  startPending = false,
+  stopPending = false,
   onCustomAction,
   onOpenConfig,
   showConfigButton = true,
@@ -1747,6 +1751,36 @@ function DeviceControlPanel({
                   },
                   children: param.options?.map((opt) => /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("option", { value: opt.value, children: opt.label }, opt.value))
                 }
+              ) : onParameterActivate && !param.readOnly ? (
+                // Tappable value: defer editing to the consumer's editor (e.g. a
+                // numpad dialog). Commit happens via onParameterChange.
+                /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)(
+                  "button",
+                  {
+                    type: "button",
+                    onClick: () => onParameterActivate(param.id, localParameterValues[param.id] ?? param.value),
+                    style: {
+                      width: "100%",
+                      height: touchSize,
+                      display: "flex",
+                      alignItems: "center",
+                      backgroundColor: "#ffffff",
+                      color: textColor,
+                      border: `1px solid ${borderColor}`,
+                      borderRadius: "6px",
+                      padding: "0 12px",
+                      fontSize: `${fontSize.input}px`,
+                      fontFamily: "Arial, sans-serif",
+                      fontWeight: 600,
+                      textAlign: "left",
+                      cursor: "pointer"
+                    },
+                    children: [
+                      localParameterValues[param.id] ?? param.value,
+                      param.unit ? ` ${param.unit}` : ""
+                    ]
+                  }
+                )
               ) : /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(
                 "input",
                 {
@@ -1785,11 +1819,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",
@@ -1797,21 +1830,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",
@@ -1819,10 +1851,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"
           }
         )
       ] }),
@@ -4457,12 +4489,13 @@ function DataOverlay({
   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;
@@ -4486,7 +4519,7 @@ function DataOverlay({
   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;
@@ -4494,8 +4527,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;
@@ -7657,7 +7691,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) {
@@ -7667,6 +7705,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);
@@ -7756,121 +7799,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,
@@ -7881,6 +7915,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,