@procaaso/alphinity-ui-components 1.1.3 → 1.3.0

package/dist/index.d.cts

@@ -1,11 +1,10 @@
 import * as react from 'react';
 import react__default from 'react';
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import * as _mui_material_OverridableComponent from '@mui/material/OverridableComponent';
 import * as _emotion_styled from '@emotion/styled';
 import * as _emotion_react from '@emotion/react';
 import * as _mui_system from '@mui/system';
 import * as _mui_material from '@mui/material';
+import * as _mui_material_OverridableComponent from '@mui/material/OverridableComponent';
 
 interface ButtonProps extends react__default.ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: 'primary' | 'secondary';
@@ -45,6 +44,126 @@ interface SelectorProps extends Omit<react__default.HTMLAttributes<HTMLDivElemen
 }
 declare const Selector: react__default.FC<SelectorProps>;
 
+/**
+ * Status levels for telemetry values
+ */
+type TelemetryStatus$1 = 'normal' | 'warning' | 'alarm' | 'fault' | 'off';
+/**
+ * Live telemetry value with status
+ */
+interface TelemetryValue {
+    /** Current value */
+    value: number | string | boolean;
+    /** Status/severity level */
+    status: TelemetryStatus$1;
+    /** Unit of measurement (optional) */
+    unit?: string;
+    /** Timestamp of last update */
+    timestamp?: number;
+    /** Quality indicator (0-100, where 100 is good) */
+    quality?: number;
+}
+/**
+ * Uniform scaling / engineering-unit (EU) metadata for an analog value.
+ *
+ * Mirrors the control program's published `scaling` record (alphinity-tffi
+ * issue #1663): one shape carries the units, EU range, raw range, and display
+ * precision for any analog tag. When present on a TelemetryBinding it is the
+ * authoritative source for units / precision / trend-axis range - the consumer
+ * passes the live published metadata here instead of static diagram config.
+ * All fields optional so a producer can omit what does not apply.
+ */
+interface ScalingMetadata {
+    /** Engineering units (e.g. "psig", "LMH", "mL"). */
+    units?: string;
+    /** Engineering-unit range low / high (trend axis + faceplate range). */
+    euLow?: number;
+    euHigh?: number;
+    /** Raw signal range low / high (AnalogInputs only). */
+    rawLow?: number;
+    rawHigh?: number;
+    /** Display decimal places. */
+    decimals?: number;
+    /** Optional descriptive metadata. */
+    description?: string;
+    sensorType?: string;
+}
+/**
+ * Telemetry data binding for a node
+ */
+interface TelemetryBinding {
+    /** Node ID this telemetry is bound to */
+    nodeId: string;
+    /** Tag/variable name for the telemetry source */
+    tag: string;
+    /** Current telemetry value */
+    value: TelemetryValue;
+    /**
+     * Uniform scaling / EU metadata (units, range, precision). When present it is
+     * the authoritative source for the displayed units, decimal precision, and
+     * trend-axis range - overriding `value.unit` / `display.precision` and the
+     * history-derived sparkline range. Populate from the live published scaling
+     * stream rather than static diagram config (#1663).
+     */
+    scaling?: ScalingMetadata;
+    /** Historical values for sparkline/trend (optional) */
+    history?: number[];
+    /** Thresholds for status determination */
+    thresholds?: {
+        /** High-High threshold (value >= this triggers alarm) */
+        highHigh?: number;
+        /** High threshold (value >= this triggers warning) */
+        high?: number;
+        /** Low threshold (value <= this triggers warning) */
+        low?: number;
+        /** Low-Low threshold (value <= this triggers alarm/fault) */
+        lowLow?: number;
+        /** Custom label for high-high threshold */
+        highHighLabel?: string;
+        /** Custom label for high threshold */
+        highLabel?: string;
+        /** Custom label for low threshold */
+        lowLabel?: string;
+        /** Custom label for low-low threshold */
+        lowLowLabel?: string;
+    };
+    /** Custom colors for status levels */
+    statusColors?: {
+        normal?: string;
+        warning?: string;
+        alarm?: string;
+        fault?: string;
+        off?: string;
+    };
+    /** Display configuration */
+    display?: {
+        /** Show value overlay above node */
+        showValue?: boolean;
+        /** Show status indicator */
+        showStatus?: boolean;
+        /** Custom label for the value */
+        label?: string;
+        /** Number of decimal places for numeric values */
+        precision?: number;
+        /** Show sparkline trend (requires history) */
+        showSparkline?: boolean;
+        /** Sparkline color (defaults to status color) */
+        sparklineColor?: string;
+        /** Custom background color (hex code or 'status' for status-based color) */
+        backgroundColor?: string;
+        /** Custom text color for value display (hex code) */
+        textColor?: string;
+        /** Horizontal offset from node center */
+        offsetX?: number;
+        /** Vertical offset from node center */
+        offsetY?: number;
+    };
+}
+/**
+ * Map of telemetry bindings by node ID
+ */
+type TelemetryMap = Map<string, TelemetryBinding>;
+
 interface ModeConfig {
     /** Units for this mode */
     unit?: string;
@@ -98,6 +217,15 @@ interface ControlPanelProps extends react__default.HTMLAttributes<HTMLDivElement
     defaultMax?: number;
     /** Default precision when no mode config is found */
     defaultPrecision?: number;
+    /**
+     * Uniform scaling / EU metadata (#1663). When provided, supplies the
+     * units / min / max / precision defaults from the live published scaling
+     * record - used only where an explicit `default*` prop or a mode config does
+     * not already set the value (modeConfig > explicit default > scaling >
+     * hardcoded). Lets the consumer drive the panel from the scaling stream
+     * instead of static diagram config.
+     */
+    scaling?: ScalingMetadata;
     /** Status state for the entire panel */
     status?: 'normal' | 'alarm' | 'warning' | 'disabled';
     /** Whether the panel is collapsed */
@@ -486,6 +614,14 @@ interface DeviceControlPanelProps {
     onStart?: () => void;
     /** Called when stop button clicked */
     onStop?: () => void;
+    /**
+     * Start command is in flight (awaiting ack). Shows a busy affordance on the
+     * START button and disables it, without locking STOP — wire from the hook's
+     * `isCommandPending(nodeId, 'start')`.
+     */
+    startPending?: boolean;
+    /** Stop command is in flight (awaiting ack). See `startPending`. */
+    stopPending?: boolean;
     /** Called when custom action clicked */
     onCustomAction?: (actionId: string) => void;
     /** Called when config button clicked (opens config panel for this device) */
@@ -501,7 +637,7 @@ interface DeviceControlPanelProps {
     /** Embedded mode - uses static positioning for rendering in containers (default: false) */
     embedded?: boolean;
 }
-declare function DeviceControlPanel({ binding, onClose, position, align, touchOptimized, compact, fontScale, maxHeight, maxWidth, toastDuration, onModeChange, onParameterChange, onStart, onStop, onCustomAction, onOpenConfig, showConfigButton, onUndock, undockIcon, modeSelectionStyle, embedded, }: DeviceControlPanelProps): react_jsx_runtime.JSX.Element | null;
+declare function DeviceControlPanel({ binding, onClose, position, align, touchOptimized, compact, fontScale, maxHeight, maxWidth, toastDuration, onModeChange, onParameterChange, onStart, onStop, startPending, stopPending, onCustomAction, onOpenConfig, showConfigButton, onUndock, undockIcon, modeSelectionStyle, embedded, }: DeviceControlPanelProps): react__default.JSX.Element | null;
 
 type DisplayMode = 'standard' | 'dashboard';
 interface FullscreenContainerProps {
@@ -699,7 +835,7 @@ declare const baseOverlayStyles: {
     };
 };
 declare const overlayStyles: Record<OverlayTheme, typeof baseOverlayStyles[OverlayTheme]>;
-declare const SVGLockedOverlay: ({ svgX, svgY, children, theme, style, className, onClick, containerSelector, }: SVGLockedOverlayProps) => react_jsx_runtime.JSX.Element;
+declare const SVGLockedOverlay: ({ svgX, svgY, children, theme, style, className, onClick, containerSelector, }: SVGLockedOverlayProps) => react.JSX.Element;
 declare const DashboardCard: _emotion_styled.StyledComponent<_mui_system.BoxOwnProps<_mui_material.Theme> & Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, keyof _mui_system.BoxOwnProps<_mui_material.Theme>> & {
     theme?: _emotion_react.Theme;
 } & {
@@ -722,11 +858,11 @@ declare const CardUnit: _emotion_styled.StyledComponent<{
     as?: React.ElementType;
 }, react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 
-declare const TrendLine: ({ values, width, height, color, strokeWidth, backgroundColor, }: TrendLineProps) => react_jsx_runtime.JSX.Element;
-declare const CircularGauge: ({ value, max, unit, label, size, color, }: CircularGaugeProps) => react_jsx_runtime.JSX.Element;
-declare const Sparkline: ({ data, width, height, color }: SparklineProps) => react_jsx_runtime.JSX.Element | null;
-declare const EquipmentIndicatorWithSparkline: ({ svgX, svgY, color, label, size, sparklineData, sparklineOffset, }: EquipmentIndicatorWithSparklineProps) => react_jsx_runtime.JSX.Element;
-declare const EquipmentIndicator: ({ svgX, svgY, color, label, size, style, className, }: EquipmentIndicatorProps) => react_jsx_runtime.JSX.Element;
+declare const TrendLine: ({ values, width, height, color, strokeWidth, backgroundColor, }: TrendLineProps) => react.JSX.Element;
+declare const CircularGauge: ({ value, max, unit, label, size, color, }: CircularGaugeProps) => react.JSX.Element;
+declare const Sparkline: ({ data, width, height, color }: SparklineProps) => react.JSX.Element | null;
+declare const EquipmentIndicatorWithSparkline: ({ svgX, svgY, color, label, size, sparklineData, sparklineOffset, }: EquipmentIndicatorWithSparklineProps) => react.JSX.Element;
+declare const EquipmentIndicator: ({ svgX, svgY, color, label, size, style, className, }: EquipmentIndicatorProps) => react.JSX.Element;
 
 declare function FullscreenWorkspace({ svgContent, overlays, leftPanel, rightPanel, footer, tabs, activeTab, onTabChange, defaultLeftCollapsed, defaultRightCollapsed, leftCollapsed: leftCollapsedProp, rightCollapsed: rightCollapsedProp, onLeftCollapseChange, onRightCollapseChange, displayMode, defaultDisplayMode, onDisplayModeChange, showDisplayModeToggle, showZoomControls, onZoomIn, onZoomOut, onResetZoom, zoomDisabled, className, ...rest }: FullscreenWorkspaceProps): react__default.ReactElement;
 
@@ -934,93 +1070,6 @@ interface SymbolMetadata {
     tags?: string[];
 }
 
-/**
- * Status levels for telemetry values
- */
-type TelemetryStatus$1 = 'normal' | 'warning' | 'alarm' | 'fault' | 'off';
-/**
- * Live telemetry value with status
- */
-interface TelemetryValue {
-    /** Current value */
-    value: number | string | boolean;
-    /** Status/severity level */
-    status: TelemetryStatus$1;
-    /** Unit of measurement (optional) */
-    unit?: string;
-    /** Timestamp of last update */
-    timestamp?: number;
-    /** Quality indicator (0-100, where 100 is good) */
-    quality?: number;
-}
-/**
- * Telemetry data binding for a node
- */
-interface TelemetryBinding {
-    /** Node ID this telemetry is bound to */
-    nodeId: string;
-    /** Tag/variable name for the telemetry source */
-    tag: string;
-    /** Current telemetry value */
-    value: TelemetryValue;
-    /** Historical values for sparkline/trend (optional) */
-    history?: number[];
-    /** Thresholds for status determination */
-    thresholds?: {
-        /** High-High threshold (value >= this triggers alarm) */
-        highHigh?: number;
-        /** High threshold (value >= this triggers warning) */
-        high?: number;
-        /** Low threshold (value <= this triggers warning) */
-        low?: number;
-        /** Low-Low threshold (value <= this triggers alarm/fault) */
-        lowLow?: number;
-        /** Custom label for high-high threshold */
-        highHighLabel?: string;
-        /** Custom label for high threshold */
-        highLabel?: string;
-        /** Custom label for low threshold */
-        lowLabel?: string;
-        /** Custom label for low-low threshold */
-        lowLowLabel?: string;
-    };
-    /** Custom colors for status levels */
-    statusColors?: {
-        normal?: string;
-        warning?: string;
-        alarm?: string;
-        fault?: string;
-        off?: string;
-    };
-    /** Display configuration */
-    display?: {
-        /** Show value overlay above node */
-        showValue?: boolean;
-        /** Show status indicator */
-        showStatus?: boolean;
-        /** Custom label for the value */
-        label?: string;
-        /** Number of decimal places for numeric values */
-        precision?: number;
-        /** Show sparkline trend (requires history) */
-        showSparkline?: boolean;
-        /** Sparkline color (defaults to status color) */
-        sparklineColor?: string;
-        /** Custom background color (hex code or 'status' for status-based color) */
-        backgroundColor?: string;
-        /** Custom text color for value display (hex code) */
-        textColor?: string;
-        /** Horizontal offset from node center */
-        offsetX?: number;
-        /** Vertical offset from node center */
-        offsetY?: number;
-    };
-}
-/**
- * Map of telemetry bindings by node ID
- */
-type TelemetryMap = Map<string, TelemetryBinding>;
-
 interface UseViewBoxOptions {
     /** Initial viewBox configuration */
     initialViewBox: ViewBox;
@@ -1412,7 +1461,7 @@ interface NodeConfigPanelProps {
  * />
  * ```
  */
-declare function NodeConfigPanel({ node, binding, onUpdateNode, onUpdateTelemetry, onAddTelemetry, onRemove, className, style, }: NodeConfigPanelProps): react_jsx_runtime.JSX.Element;
+declare function NodeConfigPanel({ node, binding, onUpdateNode, onUpdateTelemetry, onAddTelemetry, onRemove, className, style, }: NodeConfigPanelProps): react__default.JSX.Element;
 
 /**
  * Validates a diagram object structure
@@ -1518,11 +1567,28 @@ declare function calculateThresholdStatus(value: number, thresholds?: Thresholds
  */
 declare const DEFAULT_THRESHOLDS: Thresholds;
 
+/** Kinds of command a node can have in flight at once. */
+type CommandKind = 'start' | 'stop' | 'mode' | 'parameter' | 'action';
+interface UseDeviceControlsOptions {
+    /**
+     * If set (> 0), a command whose action callback does not settle within this
+     * many milliseconds is abandoned: the in-flight marker clears and a timeout
+     * result is recorded as command feedback. This only bounds how long the
+     * optional "sending…" hint shows — controls are never disabled, so a hung
+     * command can never lock anyone out regardless of this value.
+     *
+     * Note: this is a UI-level abort — it stops the HMI from *waiting*, but does
+     * not cancel an already-dispatched command (that would require the action to
+     * honor an AbortSignal). The command may still land; telemetry remains the
+     * source of truth for the resulting device state.
+     */
+    commandTimeoutMs?: number;
+}
 /**
  * Hook for managing device control bindings
  * Similar pattern to useTelemetry
  */
-declare function useDeviceControls(initialBindings?: DeviceControlBinding[]): {
+declare function useDeviceControls(initialBindings?: DeviceControlBinding[], options?: UseDeviceControlsOptions): {
     controls: DeviceControlMap;
     updateControl: (nodeId: string, updates: Partial<DeviceControlBinding>) => void;
     updateControlBatch: (updates: Record<string, Partial<DeviceControlBinding>>) => void;
@@ -1531,6 +1597,7 @@ declare function useDeviceControls(initialBindings?: DeviceControlBinding[]): {
     setControlBinding: (binding: DeviceControlBinding) => void;
     removeControlBinding: (nodeId: string) => void;
     getControlBinding: (nodeId: string) => DeviceControlBinding | undefined;
+    isCommandPending: (nodeId: string, kind?: CommandKind) => boolean;
     sendModeChange: (nodeId: string, mode: string) => Promise<void>;
     sendParameterChange: (nodeId: string, parameterId: string, value: any) => Promise<void>;
     sendStartCommand: (nodeId: string) => Promise<void>;
@@ -1816,7 +1883,7 @@ interface DeviceConfigPanelProps {
     /** Embedded mode - uses static positioning for rendering in containers (default: false) */
     embedded?: boolean;
 }
-declare function DeviceConfigPanel({ binding, onClose, onUndock, undockIcon, position, align, touchOptimized, compact, fontScale, maxHeight, maxWidth, toastDuration, onOpenControls, showControlsButton, embedded, }: DeviceConfigPanelProps): react_jsx_runtime.JSX.Element | null;
+declare function DeviceConfigPanel({ binding, onClose, onUndock, undockIcon, position, align, touchOptimized, compact, fontScale, maxHeight, maxWidth, toastDuration, onOpenControls, showControlsButton, embedded, }: DeviceConfigPanelProps): react__default.JSX.Element | null;
 
 /**
  * Options for simulation behavior
@@ -1856,4 +1923,4 @@ interface SimulationOptions {
  */
 declare function useSimulation(telemetry: TelemetryMap, updateTelemetryBatch: (updates: Array<any>) => void, options?: SimulationOptions): void;
 
-export { type AnchorType, Button, type ButtonProps, CardHeader, CardUnit, CardValue, CircularGauge, type CircularGaugeProps, type ConfigActions, type ConfigDisplay, type ConfigParameter, type ConfigSection, type ConfigState, type ConfigTheme, type ControlCapabilities, type ControlMode, ControlPanel, type ControlPanelProps, type ControlParameter, type ControlState, DEFAULT_STATUS_COLORS, DEFAULT_THRESHOLDS, DashboardCard, type DataBinding, type DeviceConfigBinding, type DeviceConfigMap, DeviceConfigPanel, type DeviceConfigPanelProps, type DeviceControlBinding, type DeviceControlMap, DeviceControlPanel, type DeviceControlPanelProps, type DeviceStatus, type Diagram, type DiagramMetadata, type DisplayMode, DisplayModeToggle, type DragPoint, type DragState, EquipmentIndicator, type EquipmentIndicatorProps, EquipmentIndicatorWithSparkline, type EquipmentIndicatorWithSparklineProps, FixedSVGContainer, FooterPanel, FullscreenContainer, FullscreenWorkspace, type FullscreenWorkspaceProps, type FullscreenWorkspaceTab, type KeyboardShortcutsOptions, LeftPanel, LeftToggleButton, LegacyValueEntry, type LegacyValueEntryProps, type ModeConfig, NodeConfigPanel, type NodeConfigPanelProps, type NodeControlConfig, NodeControlsPanel, type NodeControlsPanelProps, type NodeInstance, type Overlay, type OverlayContent, type OverlayTheme, type OverlayType, PIDCanvas, type PIDCanvasControls, type PIDCanvasFeatures, type PIDCanvasProps, PanelContent, PanelTabs, type PipeEdge, type PipeStyle, type Point, type PortDefinition, type PortInstance, type PortType, RightPanel, RightToggleButton, SVGArea, SVGLockedOverlay, type SVGLockedOverlayProps, ScrollableSVGWrapper, type SelectionState, Selector, type SelectorOption, type SelectorProps, type SimulationOptions, Sparkline, type SparklineProps, type StatusColorEntry, type StatusColorMap, StatusIndicator, type StatusIndicatorProps, type SymbolCategory, type SymbolDefinition, SymbolLibrary, type SymbolLibraryProps, type SymbolMetadata, type TelemetryBinding, type TelemetryMap, type TelemetryStatus$1 as TelemetryStatus, type TelemetryValue, ThemeProvider, ThemeToggle, type ThemeToggleProps, type Thresholds, type Transform, TrendLine, type TrendLineProps, type UseDragOptions, type UseDragResult, type UseSelectionOptions, type UseSelectionResult, type UseTelemetryOptions, type UseTelemetryResult, type UseTelemetryStatusOptions, type UseViewBoxOptions, type UseViewBoxResult, ValueEntry, type ValueEntryProps, type ViewBox, ZoomButton, ZoomControls, calculateThresholdStatus, createConfigBinding, createControlBinding, exampleDiagram, exportDiagram, generateRoutePoints, getAvailableSymbols, getPortWorldPosition, getSymbolDefinition, importDiagram, mockSymbolLibrary, nodeHasPort, overlayStyles, registerSymbol, registerSymbols, resolveStatusColor, useDeviceConfigs, useDeviceControls, useDrag, useKeyboardShortcuts, useSelection, useSimulation, useTelemetry, useTelemetryStatus, useTheme, useViewBox, validateDiagram };
+export { type AnchorType, Button, type ButtonProps, CardHeader, CardUnit, CardValue, CircularGauge, type CircularGaugeProps, type CommandKind, type ConfigActions, type ConfigDisplay, type ConfigParameter, type ConfigSection, type ConfigState, type ConfigTheme, type ControlCapabilities, type ControlMode, ControlPanel, type ControlPanelProps, type ControlParameter, type ControlState, DEFAULT_STATUS_COLORS, DEFAULT_THRESHOLDS, DashboardCard, type DataBinding, type DeviceConfigBinding, type DeviceConfigMap, DeviceConfigPanel, type DeviceConfigPanelProps, type DeviceControlBinding, type DeviceControlMap, DeviceControlPanel, type DeviceControlPanelProps, type DeviceStatus, type Diagram, type DiagramMetadata, type DisplayMode, DisplayModeToggle, type DragPoint, type DragState, EquipmentIndicator, type EquipmentIndicatorProps, EquipmentIndicatorWithSparkline, type EquipmentIndicatorWithSparklineProps, FixedSVGContainer, FooterPanel, FullscreenContainer, FullscreenWorkspace, type FullscreenWorkspaceProps, type FullscreenWorkspaceTab, type KeyboardShortcutsOptions, LeftPanel, LeftToggleButton, LegacyValueEntry, type LegacyValueEntryProps, type ModeConfig, NodeConfigPanel, type NodeConfigPanelProps, type NodeControlConfig, NodeControlsPanel, type NodeControlsPanelProps, type NodeInstance, type Overlay, type OverlayContent, type OverlayTheme, type OverlayType, PIDCanvas, type PIDCanvasControls, type PIDCanvasFeatures, type PIDCanvasProps, PanelContent, PanelTabs, type PipeEdge, type PipeStyle, type Point, type PortDefinition, type PortInstance, type PortType, RightPanel, RightToggleButton, SVGArea, SVGLockedOverlay, type SVGLockedOverlayProps, type ScalingMetadata, ScrollableSVGWrapper, type SelectionState, Selector, type SelectorOption, type SelectorProps, type SimulationOptions, Sparkline, type SparklineProps, type StatusColorEntry, type StatusColorMap, StatusIndicator, type StatusIndicatorProps, type SymbolCategory, type SymbolDefinition, SymbolLibrary, type SymbolLibraryProps, type SymbolMetadata, type TelemetryBinding, type TelemetryMap, type TelemetryStatus$1 as TelemetryStatus, type TelemetryValue, ThemeProvider, ThemeToggle, type ThemeToggleProps, type Thresholds, type Transform, TrendLine, type TrendLineProps, type UseDeviceControlsOptions, type UseDragOptions, type UseDragResult, type UseSelectionOptions, type UseSelectionResult, type UseTelemetryOptions, type UseTelemetryResult, type UseTelemetryStatusOptions, type UseViewBoxOptions, type UseViewBoxResult, ValueEntry, type ValueEntryProps, type ViewBox, ZoomButton, ZoomControls, calculateThresholdStatus, createConfigBinding, createControlBinding, exampleDiagram, exportDiagram, generateRoutePoints, getAvailableSymbols, getPortWorldPosition, getSymbolDefinition, importDiagram, mockSymbolLibrary, nodeHasPort, overlayStyles, registerSymbol, registerSymbols, resolveStatusColor, useDeviceConfigs, useDeviceControls, useDrag, useKeyboardShortcuts, useSelection, useSimulation, useTelemetry, useTelemetryStatus, useTheme, useViewBox, validateDiagram };