@procaaso/alphinity-ui-components 1.12.0 → 1.14.0

package/README.md

@@ -1,98 +1,98 @@
-# @procaaso/alphinity-ui-components
-
-A TypeScript React component library for Alphinity branded systems.
-
-## Installation
-
-```bash
-npm install @procaaso/alphinity-ui-components
-```
-
-## Usage
-
-```tsx
-import { Button, ValueEntry, StatusIndicator } from '@procaaso/alphinity-ui-components';
-import { useState } from 'react';
-
-function HMIPanel() {
-  const [temperature, setTemperature] = useState(72.5);
-  const [pressure, setPressure] = useState(14.7);
-  const [systemStatus, setSystemStatus] = useState('normal');
-
-  return (
-    <div className="p-4 space-y-4">
-      {/* System status indicators */}
-      <div className="flex gap-4 items-center">
-        <StatusIndicator status="normal" label="Power" size="medium" led={true} />
-        <StatusIndicator
-          status="alarm"
-          label="Temperature Alert"
-          animation="pulse"
-          shape="circle"
-        />
-        <StatusIndicator status="warning" label="Maintenance Due" animation="blink" />
-        <StatusIndicator status="active" label="Process Running" size="large" />
-        {/* Use "unknown" when the backend does not trust the value, such as a bad-quality
-            OPC UA read. Do not use "fault": a fault means the device itself reports a problem. */}
-        <StatusIndicator status="unknown" label="Flow Sensor" />
-      </div>
-
-      {/* Process control values */}
-      <ValueEntry
-        value={temperature}
-        onChange={setTemperature}
-        label="Temperature"
-        unit="°C"
-        min={0}
-        max={100}
-        precision={1}
-        status="normal"
-      />
-
-      <ValueEntry
-        value={pressure}
-        onChange={setPressure}
-        label="Pressure"
-        unit="PSI"
-        status="warning"
-        readOnly
-      />
-
-      {/* Control buttons */}
-      <Button variant="primary" onClick={() => console.log('Start process')}>
-        Start
-      </Button>
-    </div>
-  );
-}
-```
-
-## Development
-
-### Scripts
-
-- `npm run build` - Build the library using tsup (ESM + CJS + DTS)
-- `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
-
-- **Button** - Control buttons with primary and secondary variants for industrial actions
-- **ValueEntry** - Numeric/text input with validation, units, status indicators, and precision control
-- **StatusIndicator** - LED-style status indicators with multiple states, animations, and customizable appearance
-
-## Publishing
-
-This package is published to the npm registry at https://www.npmjs.com/package/@procaaso/alphinity-ui-components
+# @procaaso/alphinity-ui-components
+
+A TypeScript React component library for Alphinity branded systems.
+
+## Installation
+
+```bash
+npm install @procaaso/alphinity-ui-components
+```
+
+## Usage
+
+```tsx
+import { Button, ValueEntry, StatusIndicator } from '@procaaso/alphinity-ui-components';
+import { useState } from 'react';
+
+function HMIPanel() {
+  const [temperature, setTemperature] = useState(72.5);
+  const [pressure, setPressure] = useState(14.7);
+  const [systemStatus, setSystemStatus] = useState('normal');
+
+  return (
+    <div className="p-4 space-y-4">
+      {/* System status indicators */}
+      <div className="flex gap-4 items-center">
+        <StatusIndicator status="normal" label="Power" size="medium" led={true} />
+        <StatusIndicator
+          status="alarm"
+          label="Temperature Alert"
+          animation="pulse"
+          shape="circle"
+        />
+        <StatusIndicator status="warning" label="Maintenance Due" animation="blink" />
+        <StatusIndicator status="active" label="Process Running" size="large" />
+        {/* Use "unknown" when the backend does not trust the value, such as a bad-quality
+            OPC UA read. Do not use "fault": a fault means the device itself reports a problem. */}
+        <StatusIndicator status="unknown" label="Flow Sensor" />
+      </div>
+
+      {/* Process control values */}
+      <ValueEntry
+        value={temperature}
+        onChange={setTemperature}
+        label="Temperature"
+        unit="°C"
+        min={0}
+        max={100}
+        precision={1}
+        status="normal"
+      />
+
+      <ValueEntry
+        value={pressure}
+        onChange={setPressure}
+        label="Pressure"
+        unit="PSI"
+        status="warning"
+        readOnly
+      />
+
+      {/* Control buttons */}
+      <Button variant="primary" onClick={() => console.log('Start process')}>
+        Start
+      </Button>
+    </div>
+  );
+}
+```
+
+## Development
+
+### Scripts
+
+- `npm run build` - Build the library using tsup (ESM + CJS + DTS)
+- `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
+
+- **Button** - Control buttons with primary and secondary variants for industrial actions
+- **ValueEntry** - Numeric/text input with validation, units, status indicators, and precision control
+- **StatusIndicator** - LED-style status indicators with multiple states, animations, and customizable appearance
+
+## Publishing
+
+This package is published to the npm registry at https://www.npmjs.com/package/@procaaso/alphinity-ui-components

package/dist/index.cjs

@@ -88,7 +88,9 @@ __export(index_exports, {
   generateRoutePoints: () => generateRoutePoints,
   getAppearanceDefaults: () => getAppearanceDefaults,
   getAppearanceSchema: () => getAppearanceSchema,
+  getAvailableBadgeGlyphs: () => getAvailableBadgeGlyphs,
   getAvailableSymbols: () => getAvailableSymbols,
+  getBadgeGlyph: () => getBadgeGlyph,
   getPortWorldPosition: () => getPortWorldPosition,
   getSymbolDefinition: () => getSymbolDefinition,
   importDiagram: () => importDiagram,
@@ -97,6 +99,8 @@ __export(index_exports, {
   normalizeDeviceStatus: () => normalizeDeviceStatus,
   overlayStyles: () => overlayStyles,
   readAppearanceValue: () => readAppearanceValue,
+  registerBadgeGlyph: () => registerBadgeGlyph,
+  registerBadgeGlyphs: () => registerBadgeGlyphs,
   registerSymbol: () => registerSymbol,
   registerSymbols: () => registerSymbols,
   resolvePresetColor: () => resolvePresetColor,
@@ -396,6 +400,13 @@ var ISA_UNKNOWN_DARK = {
   bg: "#23263a",
   border: "#6f74a3"
 };
+var FORCED_MARK_COLOR = {
+  fill: "#ede9fe",
+  stroke: "#5b21b6",
+  bg: "#ede9fe",
+  text: "#5b21b6",
+  border: "#7c3aed"
+};
 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" },
@@ -404,14 +415,8 @@ var DEFAULT_STATUS_COLORS = {
   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" },
-  unknown: { fill: ISA_UNKNOWN.bg, stroke: ISA_UNKNOWN.border, bg: ISA_UNKNOWN.bg, text: ISA_UNKNOWN.fg, border: ISA_UNKNOWN.border }
-};
-var FORCED_MARK_COLOR = {
-  fill: "#ede9fe",
-  stroke: "#5b21b6",
-  bg: "#ede9fe",
-  text: "#5b21b6",
-  border: "#7c3aed"
+  unknown: { fill: ISA_UNKNOWN.bg, stroke: ISA_UNKNOWN.border, bg: ISA_UNKNOWN.bg, text: ISA_UNKNOWN.fg, border: ISA_UNKNOWN.border },
+  forced: FORCED_MARK_COLOR
 };
 var STATUS_ALIASES = {
   running: "normal",
@@ -1257,6 +1262,10 @@ var NodeControlsPanel = ({
 // src/components/DeviceControlPanel/DeviceControlPanel.tsx
 var import_react6 = __toESM(require("react"), 1);
 var import_jsx_runtime9 = require("react/jsx-runtime");
+var DISABLED_BUTTON_BG = "#e5e7eb";
+var DISABLED_BUTTON_TEXT = "#4b5563";
+var DISABLED_BUTTON_BORDER = "#6b7280";
+var DISABLED_BUTTON_HATCH = "repeating-linear-gradient(135deg, rgba(0,0,0,0.10) 0px, rgba(0,0,0,0.10) 4px, transparent 4px, transparent 10px)";
 function DeviceControlPanelImpl({
   binding,
   onClose,
@@ -1337,6 +1346,36 @@ function DeviceControlPanelImpl({
   const statusEntry = resolveStatusColor(binding.state.status, binding.theme?.statusColors);
   const statusColor = statusEntry.bg;
   const isUnknownStatus = normalizeDeviceStatus(binding.state.status) === "unknown";
+  const startStopRowShown = binding.display?.showStartStop !== false && (activeCapabilities?.canStart === true || activeCapabilities?.canStop === true);
+  const startEnabledNow = activeCapabilities?.canStart === true && activeCapabilities?.startEnabled !== false && !startPending;
+  const stopEnabledNow = activeCapabilities?.canStop === true && activeCapabilities?.stopEnabled !== false;
+  const startStopFontPx = Math.max(18, Math.round(18 * fontScale));
+  const startStopButtonStyle = (enabled, enabledBg) => ({
+    flex: 1,
+    minWidth: 0,
+    height: Math.max(touchSize, 56),
+    borderRadius: "6px",
+    fontSize: `${startStopFontPx}px`,
+    fontWeight: 700,
+    fontFamily: "Arial, sans-serif",
+    letterSpacing: "0.5px",
+    ...enabled ? {
+      backgroundColor: enabledBg,
+      color: "#ffffff",
+      border: "2px solid transparent",
+      cursor: "pointer",
+      opacity: 1
+    } : {
+      // Disabled look that does not depend on colour (ISA-101): a dashed
+      // border and a diagonal hatch. A grey fill alone is not enough.
+      backgroundColor: DISABLED_BUTTON_BG,
+      backgroundImage: DISABLED_BUTTON_HATCH,
+      color: DISABLED_BUTTON_TEXT,
+      border: `2px dashed ${DISABLED_BUTTON_BORDER}`,
+      cursor: "not-allowed",
+      opacity: 1
+    }
+  });
   const handleModeChange = (mode) => {
     onModeChange?.(mode);
   };
@@ -1522,6 +1561,7 @@ function DeviceControlPanelImpl({
             /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
               "div",
               {
+                "data-testid": "device-status-dot",
                 style: {
                   width: "10px",
                   height: "10px",
@@ -2107,50 +2147,45 @@ function DeviceControlPanelImpl({
           param.id
         ))
       ] }),
-      binding.display?.showStartStop !== false && (activeCapabilities?.canStart || activeCapabilities?.canStop) && /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("div", { style: { display: "flex", gap: spacing.gap, marginBottom: spacing.marginBottom }, children: [
-        activeCapabilities?.canStart && /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
-          "button",
-          {
-            onClick: onStart,
-            style: {
-              flex: 1,
-              height: touchSize,
-              backgroundColor: "#10b981",
-              color: "#ffffff",
-              border: "none",
-              borderRadius: "6px",
-              fontSize: "12px",
-              fontWeight: 700,
-              fontFamily: "Arial, sans-serif",
-              letterSpacing: "0.5px",
-              cursor: "pointer",
-              opacity: 1
-            },
-            children: startPending ? "STARTING\u2026" : "START"
-          }
-        ),
-        activeCapabilities?.canStop && /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
-          "button",
-          {
-            onClick: onStop,
-            style: {
-              flex: 1,
-              height: touchSize,
-              backgroundColor: "#ef4444",
-              color: "#ffffff",
-              border: "none",
-              borderRadius: "6px",
-              fontSize: "12px",
-              fontWeight: 700,
-              fontFamily: "Arial, sans-serif",
-              letterSpacing: "0.5px",
-              cursor: "pointer",
-              opacity: 1
-            },
-            children: stopPending ? "STOPPING\u2026" : "STOP"
-          }
-        )
-      ] }),
+      startStopRowShown && /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)(
+        "div",
+        {
+          "data-testid": "start-stop-row",
+          style: { display: "flex", gap: spacing.gap, marginBottom: spacing.marginBottom },
+          children: [
+            /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+              "button",
+              {
+                type: "button",
+                "data-control": "start",
+                "data-enabled": startEnabledNow ? "true" : "false",
+                onClick: () => {
+                  if (startEnabledNow) onStart?.();
+                },
+                disabled: !startEnabledNow,
+                "aria-busy": startPending || void 0,
+                style: startStopButtonStyle(startEnabledNow, "#10b981"),
+                children: startPending ? "STARTING\u2026" : "START"
+              }
+            ),
+            /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+              "button",
+              {
+                type: "button",
+                "data-control": "stop",
+                "data-enabled": stopEnabledNow ? "true" : "false",
+                onClick: () => {
+                  if (stopEnabledNow) onStop?.();
+                },
+                disabled: !stopEnabledNow,
+                "aria-busy": stopPending || void 0,
+                style: startStopButtonStyle(stopEnabledNow, "#ef4444"),
+                children: stopPending ? "STOPPING\u2026" : "STOP"
+              }
+            )
+          ]
+        }
+      ),
       activeCapabilities?.customActions && activeCapabilities.customActions.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("div", { style: { display: "flex", flexWrap: "wrap", gap: "8px" }, children: activeCapabilities.customActions.map((action) => {
         const actionDisabled = action.disabled === true;
         return /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)(
@@ -5150,6 +5185,32 @@ function writeAppearanceValue(node, field, value) {
   return { metadata: { ...node.metadata, [field.key]: value } };
 }
 
+// src/diagram/badges/nodeBadgeGlyphs.ts
+var PROHIBIT_GLYPH = {
+  id: "prohibit",
+  svgContent: '<circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-width="2.4"/><line x1="5.6" y1="18.4" x2="18.4" y2="5.6" stroke="currentColor" stroke-width="2.4" stroke-linecap="round"/>'
+};
+var builtInBadgeGlyphs = {
+  [PROHIBIT_GLYPH.id]: PROHIBIT_GLYPH
+};
+var customBadgeGlyphs = {};
+function registerBadgeGlyph(glyph) {
+  customBadgeGlyphs[glyph.id] = glyph;
+}
+function registerBadgeGlyphs(glyphs) {
+  if (Array.isArray(glyphs)) {
+    glyphs.forEach((glyph) => registerBadgeGlyph(glyph));
+  } else {
+    Object.values(glyphs).forEach((glyph) => registerBadgeGlyph(glyph));
+  }
+}
+function getBadgeGlyph(glyphId) {
+  return customBadgeGlyphs[glyphId] ?? builtInBadgeGlyphs[glyphId];
+}
+function getAvailableBadgeGlyphs() {
+  return [...Object.keys(customBadgeGlyphs), ...Object.keys(builtInBadgeGlyphs)];
+}
+
 // src/components/PIDCanvas/NodeRenderer.tsx
 var import_jsx_runtime17 = require("react/jsx-runtime");
 var HATCH_TILE_SIZE = 7;
@@ -5159,6 +5220,75 @@ var HATCH_STRIPE_OPACITY = 85 / 255;
 function isUnknownNode(node) {
   return node.positionUnknown === true || normalizeDeviceStatus(node.status) === "unknown";
 }
+var DEFAULT_BADGE_CORNER = "top-right";
+var DEFAULT_BADGE_SIZE = 14;
+var DEFAULT_BADGE_COLOR = "#111827";
+var DEFAULT_BADGE_BACKGROUND = "#d1d5db";
+var BADGE_GLYPH_BOX = 24;
+var BADGE_BLINK_KEYFRAME_ID = "pid-node-badge-blink-keyframes";
+var BADGE_BLINK_KEYFRAME_NAME = "pid-node-badge-blink";
+function ensureBadgeBlinkKeyframes() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(BADGE_BLINK_KEYFRAME_ID)) return;
+  const style = document.createElement("style");
+  style.id = BADGE_BLINK_KEYFRAME_ID;
+  style.textContent = `@keyframes ${BADGE_BLINK_KEYFRAME_NAME}{0%{opacity:1}50%{opacity:.15}100%{opacity:1}}`;
+  document.head.appendChild(style);
+}
+function badgeCenter(corner, vb, size) {
+  const margin = size / 4;
+  switch (corner) {
+    case "top-left":
+      return { x: -margin, y: -margin };
+    case "bottom-left":
+      return { x: -margin, y: vb.height + margin };
+    case "bottom-right":
+      return { x: vb.width + margin, y: vb.height + margin };
+    case "top-right":
+    default:
+      return { x: vb.width + margin, y: -margin };
+  }
+}
+function renderNodeBadge(badge, vb, rotation) {
+  const glyphDef = getBadgeGlyph(badge.glyph);
+  const size = badge.size ?? DEFAULT_BADGE_SIZE;
+  const color = badge.color ?? DEFAULT_BADGE_COLOR;
+  const backgroundColor = badge.backgroundColor ?? DEFAULT_BADGE_BACKGROUND;
+  const corner = badge.corner ?? DEFAULT_BADGE_CORNER;
+  const { x: cx, y: cy } = badgeCenter(corner, vb, size);
+  const radius = size / 2;
+  const glyphScale = size / BADGE_GLYPH_BOX;
+  let blinkStyle;
+  if (badge.blink) {
+    ensureBadgeBlinkKeyframes();
+    blinkStyle = {
+      animation: `${BADGE_BLINK_KEYFRAME_NAME} ${badge.blinkPeriodMs}ms ease-in-out infinite`
+    };
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime17.jsxs)(
+    "g",
+    {
+      "data-node-badge": badge.glyph,
+      "data-badge-corner": corner,
+      "data-badge-blink": badge.blink ? "true" : "false",
+      "aria-label": badge.label,
+      role: badge.label ? "img" : void 0,
+      transform: rotation ? `translate(${cx}, ${cy}) rotate(${-rotation})` : `translate(${cx}, ${cy})`,
+      style: blinkStyle,
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime17.jsx)("circle", { r: radius, fill: backgroundColor }),
+        glyphDef && /* @__PURE__ */ (0, import_jsx_runtime17.jsx)(
+          "g",
+          {
+            color,
+            transform: `scale(${glyphScale}) translate(${-BADGE_GLYPH_BOX / 2}, ${-BADGE_GLYPH_BOX / 2})`,
+            dangerouslySetInnerHTML: { __html: glyphDef.svgContent }
+          }
+        )
+      ]
+    }
+  );
+}
 function NodeRendererImpl({
   nodes: nodes2,
   selectedNodeIds,
@@ -5365,7 +5495,8 @@ function NodeRendererImpl({
                 transform: node.transform.rotation ? `rotate(${-node.transform.rotation}, ${labelX}, ${labelY})` : void 0,
                 children: node.label || node.id
               }
-            )
+            ),
+            node.badge && renderNodeBadge(node.badge, vb, node.transform.rotation)
           ]
         },
         node.id
@@ -10461,7 +10592,9 @@ function useSimulation(telemetry, updateTelemetryBatch, options = {}) {
   generateRoutePoints,
   getAppearanceDefaults,
   getAppearanceSchema,
+  getAvailableBadgeGlyphs,
   getAvailableSymbols,
+  getBadgeGlyph,
   getPortWorldPosition,
   getSymbolDefinition,
   importDiagram,
@@ -10470,6 +10603,8 @@ function useSimulation(telemetry, updateTelemetryBatch, options = {}) {
   normalizeDeviceStatus,
   overlayStyles,
   readAppearanceValue,
+  registerBadgeGlyph,
+  registerBadgeGlyphs,
   registerSymbol,
   registerSymbols,
   resolvePresetColor,