@mp70/react-networks 0.5.0-alpha.0 → 0.5.1

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import React$1, { Component, ReactNode, ErrorInfo } from 'react';
+import React$1, { Component, ReactNode, ErrorInfo, CSSProperties } from 'react';
+import * as reactflow from 'reactflow';
 import { Node, NodeTypes, EdgeTypes, Connection, Edge, ConnectionMode, ReactFlowInstance, Viewport, FitViewOptions, NodeProps, EdgeProps } from 'reactflow';
 
 type FibreFlowCableKind = 'simple' | 'tube';
@@ -65,7 +66,7 @@ interface NetBoxDeviceTransformOptions {
     includeInterfacePorts?: boolean;
     /** Include per-port position metadata when provided */
     includePortPositions?: boolean;
-    /** Optional mapper for full control over interface->port mapping */
+    /** Optional mapper for full control over interface-to-port mapping */
     mapInterfaceToPort?: (args: {
         device: NetBoxDevice;
         iface: NetBoxInterface;
@@ -78,6 +79,7 @@ interface NetBoxDevice {
     device_type: {
         id: number;
         model: string;
+        u_height?: number;
         manufacturer: {
             name: string;
         };
@@ -239,7 +241,7 @@ declare enum Width {
  * Port type enumeration
  * @public
  */
-type PortType = 'ethernet' | 'fiber' | 'console' | 'mgmt' | 'usb' | 'power_ac' | 'power_c13' | 'power_c19';
+type PortType = 'ethernet' | 'rj45' | 'fiber' | 'console' | 'mgmt' | 'usb' | 'power_ac' | 'power_c13' | 'power_c19';
 /**
  * Cable types used for connected network ports.
  * @public
@@ -296,6 +298,10 @@ interface PortPosition {
     xPercent?: number;
     /** Absolute Y position as percentage (0-100) */
     yPercent?: number;
+    /** Authored port width as a percentage of the rendered image frame */
+    widthPercent?: number;
+    /** Authored port height as a percentage of the rendered image frame */
+    heightPercent?: number;
 }
 /**
  * Recommended simple port input for device and PDU rendering.
@@ -309,9 +315,11 @@ interface DevicePort {
     /** Display label for the port */
     label: string;
     /** Front/rear device face. `back` is accepted as an alias for `rear`. */
-    face?: DeviceView | 'back';
+    face?: DeviceFace | 'back';
     /** Optional block/group name (for example `Network Ports`, `QSFP28`, `Power Ports`) */
     group?: string;
+    /** Optional source/detected family label used for visual kind inference */
+    sourceTypeLabel?: string;
     /** Whether the port is currently connected */
     connected?: boolean;
     /** Type of port for styling and validation */
@@ -336,6 +344,8 @@ interface Port {
     id?: string;
     /** Display label for the port */
     label: string;
+    /** Optional source/detected family label used for visual kind inference */
+    sourceTypeLabel?: string;
     /** Whether the port is currently connected */
     connected: boolean;
     /** Type of port for styling and validation */
@@ -370,10 +380,21 @@ type NetworkNodeType = 'rack' | 'switch' | 'router' | 'server' | 'fiber' | 'patc
  */
 type DeviceStatus = 'active' | 'inactive' | 'maintenance';
 /**
- * Device view orientations
+ * Device face orientations
  * @public
  */
-type DeviceView = 'front' | 'rear';
+type DeviceFace = 'front' | 'rear';
+type DiagramPortHandleRef = {
+    nodeId: string;
+    handleId: string;
+};
+type DiagramPortClickPayload = {
+    nodeId: string;
+    handleId: string;
+    groupName: string;
+    portLabel: string;
+    face: DeviceFace;
+};
 /**
  * Rack rendering layout modes.
  * @public
@@ -404,12 +425,14 @@ interface NetworkNodeDataBase extends DeviceImageOptions {
     label: string;
     /** Current status of the node/device */
     status?: DeviceStatus | string;
-    /** Simple flat port input. Use `portGroups` / `rearPortGroups` for explicit grouped control. */
-    ports?: DevicePort[] | number;
+    /** Simple flat port input or grouped port blocks. Use `portGroups` / `rearPortGroups` for explicit grouped control. */
+    ports?: DevicePort[] | PortBlock[] | number;
     /** Advanced grouped front port input */
     portGroups?: PortBlock[];
     /** Advanced grouped rear port input */
     rearPortGroups?: PortBlock[];
+    /** Grouped rear port blocks (rack JSON alias for `rearPortGroups`) */
+    rearPorts?: PortBlock[];
     /** List of connected node IDs */
     connections?: string[];
     /** NetBox integration ID */
@@ -426,10 +449,8 @@ interface NetworkNodeDataBase extends DeviceImageOptions {
     uPosition?: number;
     /** Whether this node is currently mounted inside a rack container */
     isRackMounted?: boolean;
-    /** Current front/rear view orientation */
-    view?: DeviceView;
-    /** Rack face orientation */
-    face?: DeviceView;
+    /** Front/rear orientation for devices and rack faces */
+    face?: DeviceFace;
     /** Rack rendering layout mode */
     rackLayout?: RackLayoutMode;
     /** Gap in pixels between front and rear faces in split-face mode */
@@ -438,13 +459,18 @@ interface NetworkNodeDataBase extends DeviceImageOptions {
     mountMode?: RackMountMode;
     /** Device type specification */
     deviceType?: string;
+    /**
+     * When false, device elevation renders as a status-colored block without front/rear photos.
+     * Defaults to true (show photos when URLs exist).
+     */
+    showDeviceImages?: boolean;
     /** Device manufacturer */
     manufacturer?: string;
     /** Device role in network */
     role?: string;
     /** Device width configuration */
     width?: Width | number;
-    /** Power port side for rear view */
+    /** Power port side for rear face */
     powerSide?: PowerSide;
     /** Vertical PDU height in centimeters */
     heightCm?: number;
@@ -552,7 +578,7 @@ interface NetworkNodeDataBase extends DeviceImageOptions {
     height?: number;
     headerHeight?: number;
     /** Optional precomputed map for handle-to-face resolution */
-    handleSideMap?: Record<string, DeviceView>;
+    handleSideMap?: Record<string, DeviceFace>;
     /** Additional extension metadata */
     metadata?: Record<string, unknown>;
 }
@@ -568,7 +594,7 @@ interface RackNodeData extends NetworkNodeDataBase {
  * @public
  */
 interface DeviceNodeData extends NetworkNodeDataBase {
-    ports?: DevicePort[] | number;
+    ports?: DevicePort[] | PortBlock[] | number;
 }
 /**
  * Fibre flow cable node data.
@@ -714,7 +740,9 @@ type NetworkEdge<TData extends NetworkEdgeData = NetworkEdgeData> = {
     data?: TData;
 };
 /**
- * High-level document format independent from React Flow handle ids.
+ * Canonical persisted/editor document schema independent from React Flow handle ids.
+ * Prefer this model for saving diagrams, syncing external systems, and controlled
+ * document-mode usage via `document` / `onDocumentChange`.
  * @public
  */
 interface DiagramDocument {
@@ -758,7 +786,7 @@ interface DiagramNodePlacement {
 interface DiagramEndpoint {
     id: string;
     label: string;
-    face?: DeviceView | 'internal';
+    face?: DeviceFace | 'internal';
     group?: string;
     role?: 'network' | 'power' | 'fiber' | 'tube' | 'splice' | 'coupler' | 'splitter' | 'cable' | 'generic';
     medium?: 'ethernet' | 'fiber' | 'power' | 'tube' | 'generic';
@@ -774,8 +802,7 @@ interface DiagramEndpoint {
  */
 interface DiagramNodeRender {
     status?: DeviceStatus | string;
-    view?: DeviceView;
-    face?: DeviceView;
+    face?: DeviceFace;
     width?: Width | number;
     widthPx?: number;
     height?: number;
@@ -844,9 +871,8 @@ interface DiagramEdge {
  */
 interface DiagramUiState {
     nodeState?: Record<string, {
-        view?: DeviceView;
-        face?: DeviceView;
-        handleSideMap?: Record<string, DeviceView>;
+        face?: DeviceFace;
+        handleSideMap?: Record<string, DeviceFace>;
     }>;
     metadata?: Record<string, unknown>;
 }
@@ -905,15 +931,17 @@ interface RackDevice extends DeviceImageOptions {
     mountMode?: RackMountMode;
     /** Device role in network */
     role?: string;
-    /** Recommended simple port input. Use `portGroups` / `rearPortGroups` for explicit grouped control. */
-    ports?: DevicePort[];
+    /** Recommended simple port input (flat `DevicePort[]` or grouped `PortBlock[]`). */
+    ports?: DevicePort[] | PortBlock[];
     /** Current status of the device */
     status?: DeviceStatus | string;
     /** Advanced grouped front port input */
     portGroups?: PortBlock[];
     /** Advanced grouped rear port input */
     rearPortGroups?: PortBlock[];
-    /** Power port side for rear view */
+    /** Grouped rear port blocks (rack JSON alias for `rearPortGroups`) */
+    rearPorts?: PortBlock[];
+    /** Power port side for rear face */
     powerSide?: PowerSide;
     /** Connected device IDs */
     connections?: string[];
@@ -1081,36 +1109,43 @@ interface NetworkDiagramFlowMethods {
     getEdges: () => NetworkEdge[];
     fitView: (options?: NetworkDiagramFitViewOptions) => void;
 }
+/**
+ * Store state shape used by `NetworkDiagramStoreApi`.
+ * @public
+ */
+interface NetworkDiagramStoreState {
+    nodes: NetworkNode[];
+    edges: NetworkEdge[];
+    debug?: boolean;
+}
+/**
+ * Store connection validation parameters.
+ * @public
+ */
+interface NetworkDiagramValidateConnectionParams {
+    source: string | null;
+    target: string | null;
+    sourceHandle?: string | null;
+    targetHandle?: string | null;
+}
+/**
+ * Store connection validation result.
+ * @public
+ */
+interface NetworkDiagramValidationResult {
+    valid: boolean;
+    reason?: string;
+}
 /**
  * Store contract accepted by `NetworkDiagram`.
  * @public
  */
 interface NetworkDiagramStoreApi {
-    getState: () => {
-        nodes: NetworkNode[];
-        edges: NetworkEdge[];
-        debug?: boolean;
-    };
-    setState: (partial: Partial<{
-        nodes: NetworkNode[];
-        edges: NetworkEdge[];
-        debug?: boolean;
-    }>) => void;
-    subscribe: (listener: (state: {
-        nodes: NetworkNode[];
-        edges: NetworkEdge[];
-        debug?: boolean;
-    }) => void) => () => void;
+    getState: () => NetworkDiagramStoreState;
+    setState: (partial: Partial<NetworkDiagramStoreState>) => void;
+    subscribe: (listener: (state: NetworkDiagramStoreState) => void) => () => void;
     selectEdgeZIndex: (edge: NetworkEdge) => number;
-    validateConnection: (params: {
-        source: string | null;
-        target: string | null;
-        sourceHandle?: string | null;
-        targetHandle?: string | null;
-    }) => {
-        valid: boolean;
-        reason?: string;
-    };
+    validateConnection: (params: NetworkDiagramValidateConnectionParams) => NetworkDiagramValidationResult;
     selectNodeById: (id: string) => NetworkNode | undefined;
     selectConnectedEdges: (nodeId: string) => NetworkEdge[];
 }
@@ -1157,10 +1192,10 @@ interface NetworkDiagramProps {
     isValidConnection?: (connection: Connection) => boolean;
     /** Optional connection mode override */
     connectionMode?: ConnectionMode;
-    /** Callback when device view changes */
-    onViewChange?: (nodeId: string, view: DeviceView) => void;
+    /** Callback when a device face changes */
+    onFaceChange?: (nodeId: string, face: DeviceFace) => void;
     /** Callback when rack face changes */
-    onRackFaceChange?: (rackId: string, face: DeviceView) => void;
+    onRackFaceChange?: (rackId: string, face: DeviceFace) => void;
     /** CSS class name */
     className?: string;
     /** Inline styles */
@@ -1191,16 +1226,33 @@ interface NetworkDiagramProps {
     interaction?: NetworkDiagramInteractionOptions;
     /** Configuration for the floating action panel shown on selected rack/device nodes. */
     actionPanel?: NetworkDiagramActionPanelOptions;
-    /** Enable connecting edges by clicking on handles. When true, increases handle sizes for better touch targets. Default is true. */
-    connectOnClick?: boolean;
-    /** Disable panning on drag. Default is false. */
-    panOnDrag?: boolean;
-    /** Disable panning on scroll. Default is true. */
-    panOnScroll?: boolean;
-    /** Disable zooming on scroll. Default is true. */
-    zoomOnScroll?: boolean;
     /** Optional fitView options passed to React Flow */
     fitViewOptions?: FitViewOptions;
+    /**
+     * Let React Flow render only viewport-visible nodes and edges.
+     * Defaults to true, matching the library's existing large-diagram behavior.
+     */
+    onlyRenderVisibleElements?: boolean;
+    /** Node IDs to keep at full opacity when diagram focus dimming is enabled */
+    highlightedNodeIds?: string[];
+    /** Edge IDs to keep at full opacity when diagram focus dimming is enabled */
+    highlightedEdgeIds?: string[];
+    /**
+     * When true, non-highlighted nodes and edges are dimmed while focus IDs are set.
+     * Edges connected to highlighted nodes remain in focus unless
+     * `connectEdgesToHighlightedNodes` is false.
+     */
+    dimUnhighlighted?: boolean;
+    /** Opacity for dimmed nodes/edges (0-1). Defaults to 0.25 */
+    dimOpacity?: number;
+    /** When false, only explicit highlightedEdgeIds stay bright during focus. */
+    connectEdgesToHighlightedNodes?: boolean;
+    /** When false, devices render without rack photos. Status border still uses `getStatusColor`. Default true. */
+    showDeviceImages?: boolean;
+    /** Port handles kept highlighted during diagram trace/focus. */
+    highlightedPortHandles?: DiagramPortHandleRef[];
+    /** Fired when a port handle is clicked (typically in read-only trace mode). */
+    onPortClick?: (payload: DiagramPortClickPayload) => void;
 }
 
 declare const NetworkDiagram: React$1.FC<NetworkDiagramProps>;
@@ -1213,7 +1265,7 @@ interface DiagramErrorBoundaryProps {
     /** Optional callback when an error is caught (e.g. for logging) */
     onError?: (error: Error, errorInfo: ErrorInfo) => void;
 }
-interface State {
+interface DiagramErrorBoundaryState {
     error: Error | null;
 }
 /**
@@ -1236,104 +1288,45 @@ interface State {
  * </DiagramErrorBoundary>
  * ```
  */
-declare class DiagramErrorBoundary extends Component<DiagramErrorBoundaryProps, State> {
-    state: State;
-    static getDerivedStateFromError(error: Error): State;
+declare class DiagramErrorBoundary extends Component<DiagramErrorBoundaryProps, DiagramErrorBoundaryState> {
+    state: DiagramErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): DiagramErrorBoundaryState;
     componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
     reset: () => void;
     render(): ReactNode;
 }
 
 interface RackNodeProps extends NodeProps<NetworkNode['data']> {
-    onViewChange?: (nodeId: string, view: 'front' | 'rear') => void;
+    onFaceChange?: (nodeId: string, face: 'front' | 'rear') => void;
     onRackFaceChange?: (rackId: string, face: 'front' | 'rear') => void;
     isDragOver?: boolean;
 }
-/**
- * Rack visualization component with U positioning support.
- *
- * Displays a 19" rack with configurable height, front/rear view switching,
- * and support for mounting devices at specific U positions.
- *
- * @example
- * ```tsx
- * {
- *   id: 'rack-1',
- *   type: 'rack',
- *   position: { x: 100, y: 100 },
- *   data: {
- *     label: 'Main Rack',
- *     uHeight: 42,
- *     status: 'active'
- *   }
- * }
- * ```
- *
- * @public
- */
-declare const RackNode: React$1.FC<RackNodeProps>;
+/** Memoized; uses useStoreApi (not useReactFlow) so rack chrome does not re-render on every node move. */
+declare const RackNode: React$1.NamedExoticComponent<RackNodeProps>;
 
 declare const FiberNode: React$1.FC<NodeProps<NetworkNode['data']>>;
 
-/**
- * Fiber edge component for connecting fiber ports between nodes.
- *
- * Supports both single fiber connections with color coding and ribbon fiber
- * connections (6-12 fibers) with parallel stripe visualization.
- *
- * @example
- * ```tsx
- * {
- *   id: 'edge-1',
- *   source: 'node-1',
- *   target: 'node-2',
- *   sourceHandle: 'fiber-1',
- *   targetHandle: 'fiber-2',
- *   type: 'fiber',
- *   data: {
- *     kind: 'fiber',
- *     ribbonFiberIds: [1, 2, 3, 4, 5, 6] // For ribbon mode
- *   }
- * }
- * ```
- *
- * @public
- */
-declare const FiberEdge: React$1.FC<EdgeProps<NetworkEdge['data']> & {
+declare const FiberEdge: React$1.NamedExoticComponent<Pick<reactflow.Edge<NetworkEdgeData | undefined>, "id" | "data" | "source" | "target" | "style" | "selected" | "animated"> & Pick<reactflow.WrapEdgeProps<any>, "sourcePosition" | "targetPosition" | "interactionWidth" | "sourceX" | "sourceY" | "targetX" | "targetY" | "sourceHandleId" | "targetHandleId"> & {
+    label?: string | React$1.ReactNode;
+    labelStyle?: React$1.CSSProperties;
+    labelShowBg?: boolean;
+    labelBgStyle?: React$1.CSSProperties;
+    labelBgPadding?: [number, number];
+    labelBgBorderRadius?: number;
+} & {
+    markerStart?: string;
+    markerEnd?: string;
+    pathOptions?: any;
+} & {
     className?: string;
 }>;
 
-declare const PowerEdge: React$1.FC<EdgeProps>;
+declare const PowerEdge: React$1.NamedExoticComponent<EdgeProps>;
 
-/**
- * Device visualization component with port management.
- *
- * Represents a device that can be placed in a rack. Supports port configuration,
- * U positioning, front/rear views, and various device types (servers, switches, routers, etc.).
- *
- * @example
- * ```tsx
- * {
- *   id: 'server-1',
- *   type: 'device',
- *   position: { x: 120, y: 150 },
- *   parentId: 'rack-1',
- *   data: {
- *     label: 'Web Server',
- *     deviceType: 'server',
- *     uPosition: 1,
- *     ports: [
- *       { id: 'eth0', label: 'eth0', group: 'Network Ports', connected: true, type: 'ethernet' }
- *     ]
- *   }
- * }
- * ```
- *
- * @public
- */
-declare const DeviceNode: React$1.FC<NodeProps<NetworkNode['data']>>;
+/** Memoized to avoid re-rendering rack devices when unrelated nodes move (React Flow perf guide). */
+declare const DeviceNode: React$1.NamedExoticComponent<NodeProps<NetworkNodeDataBase | RackNodeData | DeviceNodeData | FibreFlowCableNodeData | FibreFlowClosureNodeData>>;
 
-declare const VerticalPDU: React$1.FC<NodeProps<NetworkNode['data']>>;
+declare const VerticalPDU: React$1.NamedExoticComponent<NodeProps<NetworkNodeDataBase | RackNodeData | DeviceNodeData | FibreFlowCableNodeData | FibreFlowClosureNodeData>>;
 
 declare const SpliceNode: React$1.FC<NodeProps<NetworkNode['data']>>;
 
@@ -1400,9 +1393,7 @@ interface FibreFlowMapProps {
     className?: string;
     style?: React$1.CSSProperties;
     readOnly?: boolean;
-    panOnDrag?: boolean;
-    panOnScroll?: boolean;
-    zoomOnScroll?: boolean;
+    interaction?: NetworkDiagramInteractionOptions;
 }
 declare const FibreFlowMap: React$1.FC<FibreFlowMapProps>;
 
@@ -1543,6 +1534,14 @@ declare const inventoryToNetworkDiagram: (data: {
     nodes: NetworkNode[];
     edges: NetworkEdge[];
 };
+/**
+ * Convert inventory data directly into the canonical DiagramDocument model.
+ */
+declare const inventoryToDiagramDocument: (data: {
+    racks: InventoryRackDTO[];
+    devices: InventoryDeviceDTO[];
+    cables: InventoryCableDTO[];
+}) => DiagramDocument;
 /**
  * Generate simple layout positions for nodes array
  */
@@ -1571,6 +1570,14 @@ declare const netboxToNetworkDiagram: (data: {
     nodes: NetworkNode[];
     edges: NetworkEdge[];
 };
+/**
+ * Convert NetBox data directly into the canonical DiagramDocument model.
+ */
+declare const netboxToDiagramDocument: (data: {
+    racks: NetBoxRack[];
+    devices: NetBoxDevice[];
+    cables: NetBoxCable[];
+}, options?: NetBoxDeviceTransformOptions) => DiagramDocument;
 /**
  * Calculate U position for devices in a rack
  */
@@ -2088,18 +2095,186 @@ declare function addSpliceToTray(trays: SpliceTrayConfig[], trayId: string, spli
  */
 declare function removeSpliceFromTray(trays: SpliceTrayConfig[], trayId: string, spliceId: string): SpliceTrayConfig[];
 
-type PortFaces = {
+/**
+ * Normalize flat `DevicePort[]` input into explicit front/rear grouped blocks.
+ * This is the bridge between the recommended simple port schema and the
+ * lower-level grouped renderer input.
+ * @public
+ */
+declare function buildPortBlocksFromPorts(devicePorts: DevicePort[]): {
     ports: PortBlock[];
     rearPorts: PortBlock[];
 };
-type PortFaceData = Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'>;
-declare function buildPortBlocksFromPorts(devicePorts: DevicePort[]): PortFaces;
-declare function getResolvedPortBlocks(data: PortFaceData | undefined): PortFaces;
-declare function getFrontPortBlocks(data: PortFaceData | undefined): PortBlock[];
-declare function getRearPortBlocks(data: PortFaceData | undefined): PortBlock[];
-declare function hasFrontPorts(data: PortFaceData | undefined): boolean;
-declare function hasRearPorts(data: PortFaceData | undefined): boolean;
-declare function getDefaultDeviceView(data: PortFaceData | undefined): DeviceView;
+/**
+ * Resolve the grouped front/rear port blocks from either supported input form:
+ * flat `ports: DevicePort[]` or explicit `portGroups` / `rearPortGroups`.
+ * @public
+ */
+type ResolvedPortBlockInput = Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> & {
+    rearPorts?: PortBlock[];
+};
+declare function getResolvedPortBlocks(data: ResolvedPortBlockInput | undefined): {
+    ports: PortBlock[];
+    rearPorts: PortBlock[];
+};
+/**
+ * Resolve the front-facing grouped port blocks for a node/device data object.
+ * @public
+ */
+declare function getFrontPortBlocks(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): PortBlock[];
+/**
+ * Resolve the rear-facing grouped port blocks for a node/device data object.
+ * @public
+ */
+declare function getRearPortBlocks(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): PortBlock[];
+/**
+ * Determine whether a node/device data object resolves to any front ports.
+ * @public
+ */
+declare function hasFrontPorts(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): boolean;
+/**
+ * Determine whether a node/device data object resolves to any rear ports.
+ * @public
+ */
+declare function hasRearPorts(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): boolean;
+/**
+ * Choose the default device face based on the resolved front/rear port data.
+ * @public
+ */
+declare function getDefaultDeviceFace(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): DeviceFace;
+
+/**
+ * Normalize source/target directional suffixes used for bidirectional handles.
+ * Example: `Rear Ports-1-target` -\> `Rear Ports-1`.
+ */
+declare function normalizeDirectionalHandleId(handleId: string | null | undefined): string;
+/**
+ * Normalize rendered handle ids back to their canonical endpoint id.
+ * This removes both directional suffixes and split-face rear aliases.
+ */
+declare function normalizeHandleId(handleId: string | null | undefined): string;
+/**
+ * Returns true when a port type is considered power-related.
+ */
+declare function isPowerPortType(portType: string | undefined): boolean;
+/**
+ * Build a stable handle id for a port.
+ * Power ports use the label directly to preserve legacy ids.
+ */
+declare function buildPortHandleId(portBlockName: string, port: Pick<Port, 'label' | 'id'> & {
+    type?: string;
+}): string;
+/**
+ * Heuristic for whether a handle id represents a power endpoint.
+ */
+declare function looksLikePowerHandleId(handleId: string): boolean;
+
+/**
+ * Resolve the effective device face for a flat port input.
+ * @public
+ */
+declare function resolveDevicePortFace(port: Pick<DevicePort, 'face' | 'type'>): DeviceFace;
+/** @deprecated Use {@link resolveDevicePortFace}. */
+declare const resolveReactNetworksPortFace: typeof resolveDevicePortFace;
+/**
+ * Resolve the effective port group name for a flat port input.
+ * @public
+ */
+declare function resolveDevicePortGroup(port: Pick<DevicePort, 'face' | 'group' | 'type'>): string;
+/** @deprecated Use {@link resolveDevicePortGroup}. */
+declare const resolveReactNetworksPortGroup: typeof resolveDevicePortGroup;
+/**
+ * Normalize unknown port array input into canonical flat {@link DevicePort} entries.
+ * @public
+ */
+declare function normalizeDevicePorts(value: unknown): DevicePort[] | undefined;
+/** @deprecated Use {@link normalizeDevicePorts}. */
+declare const normalizeReactNetworksPorts: typeof normalizeDevicePorts;
+/**
+ * Resolve flat device ports from node data supporting flat or grouped port input.
+ * @public
+ */
+declare function resolveNodeDevicePorts(value: unknown): DevicePort[] | undefined;
+/** @deprecated Use {@link resolveNodeDevicePorts}. */
+declare const resolveReactNetworksNodePorts: typeof resolveNodeDevicePorts;
+/**
+ * Flatten grouped port blocks into canonical flat {@link DevicePort} entries.
+ * @public
+ */
+declare function flattenDevicePortsFromGroups({ portGroups, rearPortGroups, }: {
+    portGroups?: PortBlock[];
+    rearPortGroups?: PortBlock[];
+}): DevicePort[];
+/** @deprecated Use {@link flattenDevicePortsFromGroups}. */
+declare const flattenReactNetworksPortGroups: typeof flattenDevicePortsFromGroups;
+/**
+ * Build grouped port blocks from flat device port input.
+ * @public
+ */
+declare function buildDevicePortGroupsFromPorts(ports: DevicePort[] | undefined): {
+    portGroups: PortBlock[];
+    rearPortGroups: PortBlock[];
+};
+/** @deprecated Use {@link buildDevicePortGroupsFromPorts}. */
+declare const buildReactNetworksPortGroupsFromPorts: typeof buildDevicePortGroupsFromPorts;
+interface ListPossiblePortHandleIdsOptions {
+    deviceType?: string;
+    face?: DeviceFace;
+}
+/**
+ * List handle ids that may exist on a rendered node for a port.
+ * @public
+ */
+declare function listPossiblePortHandleIds(portBlockName: string, port: Pick<Port, 'id' | 'label' | 'type'>, options?: ListPossiblePortHandleIdsOptions): string[];
+/**
+ * Validate that a handle id exists on node data after grouping resolution.
+ * @public
+ */
+declare function validatePortHandleOnNodeData(nodeData: Pick<NetworkNodeDataBase, 'ports' | 'portGroups' | 'rearPortGroups'> | undefined, handle: string, options?: {
+    deviceType?: string;
+    sanitizeHandle?: (value: string) => string;
+}): boolean;
+/**
+ * Convert flat ports to grouped blocks using the same rules as renderers.
+ * @public
+ */
+declare function resolveDevicePortBlocksFromFlatPorts(ports: DevicePort[]): {
+    portGroups: PortBlock[];
+    rearPortGroups: PortBlock[];
+};
+
+declare const parseSemanticPortPosition: (value: string) => PortPosition | undefined;
+declare const normalizePortPositionInput: (value: unknown) => PortPosition | undefined;
+
+type PathLayoutDirection = 'horizontal' | 'vertical';
+interface PathLayoutStepInput {
+    id: string;
+    type?: NetworkNode['type'];
+    data?: NetworkNode['data'];
+}
+interface PathLayoutEdgeInput {
+    id: string;
+    source: string;
+    target: string;
+    type?: NetworkEdge['type'];
+    data?: NetworkEdge['data'];
+}
+interface BuildPathLayoutOptions {
+    direction?: PathLayoutDirection;
+    spacing?: number;
+    origin?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Lay out a sequential path of nodes and connecting edges with deterministic spacing.
+ * @public
+ */
+declare function buildPathLayoutGraph(steps: PathLayoutStepInput[], edges: PathLayoutEdgeInput[], options?: BuildPathLayoutOptions): {
+    nodes: NetworkNode[];
+    edges: NetworkEdge[];
+};
 
 interface NetworkGraphSnapshot {
     nodes: NetworkNode[];
@@ -2111,7 +2286,7 @@ declare function diagramDocumentToNetworkGraph(document: DiagramDocument): Netwo
 type EndpointConnectionKind = 'power' | 'network' | 'unknown';
 interface EndpointMetadata {
     normalizedHandle: string;
-    face?: DeviceView;
+    face?: DeviceFace;
     kind: EndpointConnectionKind;
     compatibility: string[];
 }
@@ -2125,6 +2300,23 @@ declare function resolveEndpointCompatibilityKeys(input: {
 }): string[];
 declare function getEndpointMetadata(node?: NetworkNode, handle?: string | null): EndpointMetadata;
 
+type PortVisualKind = 'generic' | 'rj45' | 'sfp' | 'qsfp' | 'osfp' | 'console' | 'usb' | 'power_c13' | 'power_c19' | 'power_ac';
+interface PortVisualInput {
+    type?: PortType | string;
+    label?: string;
+    id?: string;
+    group?: string;
+    sourceTypeLabel?: string;
+    connectorType?: string;
+}
+interface PortVisualDimensions {
+    width: number;
+    height: number;
+    borderRadius: string;
+}
+declare function resolvePortVisualKind(input: PortVisualInput): PortVisualKind;
+declare function getStandardPortVisualDimensions(inputOrKind: PortVisualInput | PortVisualKind): PortVisualDimensions | undefined;
+
 /**
  * Power connector utilities for consistent styling across devices and PDUs
  */
@@ -2291,6 +2483,41 @@ interface ReplaceEdgeOptions {
  */
 declare function replaceEdge(options: ReplaceEdgeOptions): Edge[] | null;
 
+interface DiagramFocusOptions {
+    highlightedNodeIds?: readonly string[];
+    highlightedEdgeIds?: readonly string[];
+    dimUnhighlighted?: boolean;
+    dimOpacity?: number;
+    /** When false, only explicit highlightedEdgeIds stay bright (not every edge on a highlighted node). */
+    connectEdgesToHighlightedNodes?: boolean;
+}
+declare const DEFAULT_DIAGRAM_DIM_OPACITY = 0.25;
+declare function hasDiagramFocus(options: DiagramFocusOptions): boolean;
+declare function isNodeInDiagramFocus(nodeId: string, options: DiagramFocusOptions): boolean;
+declare function isEdgeInDiagramFocus(edgeId: string, edge: Pick<NetworkEdge, 'source' | 'target'>, options: DiagramFocusOptions): boolean;
+type RuntimeNode = NetworkNode & {
+    style?: CSSProperties;
+};
+type RuntimeEdge = NetworkEdge & {
+    style?: CSSProperties;
+};
+declare function applyDiagramFocusToNodes<TNode extends RuntimeNode>(nodes: TNode[], options: DiagramFocusOptions): TNode[];
+declare function applyDiagramFocusToEdges<TEdge extends RuntimeEdge>(edges: TEdge[], options: DiagramFocusOptions): TEdge[];
+
+declare function isDeviceDiagramNode(node: NetworkNode): boolean;
+declare function applyDeviceDisplayToNodes(nodes: NetworkNode[], options?: {
+    showDeviceImages?: boolean;
+}, previousNodes?: NetworkNode[]): NetworkNode[];
+
+type DiagramPortContextValue = {
+    highlightedPortHandles?: readonly DiagramPortHandleRef[];
+    onPortClick?: (payload: DiagramPortClickPayload) => void;
+    portClickEnabled: boolean;
+};
+declare const DiagramPortProvider: React$1.Provider<DiagramPortContextValue>;
+declare function useDiagramPortInteraction(): DiagramPortContextValue;
+declare function isDiagramPortHandleHighlighted(highlightedPortHandles: readonly DiagramPortHandleRef[] | undefined, nodeId: string, handleId: string): boolean;
+
 /**
  * Template Schema V2 — unified device template model.
  *
@@ -2600,4 +2827,4 @@ declare function useNetworkDiagram(store: NetworkDiagramStore): NetworkDiagramSt
 declare function useNodes(store: NetworkDiagramStore): NetworkNode[];
 declare function useEdges(store: NetworkDiagramStore): NetworkEdge[];
 
-export { COUPLERS_PER_PANEL, COUPLER_SLOT_HEIGHT_PX, COUPLER_WIDTH_PX, CableNode, ClosureNode, CouplerNode, type DeviceImageFit, type DeviceImageOptions, type DeviceImageRepeat, DeviceNode, DevicePlacementError, type DevicePlacementValidation, type DevicePort, type DeviceStatus, type DeviceTemplateV2, type DeviceView, type DiagramDocument, type DiagramEdge, type DiagramEdgeEndpoint, type DiagramEndpoint, DiagramErrorBoundary, type DiagramErrorBoundaryProps, type DiagramExternalRef, type DiagramNode, type DiagramNodeKind, type DiagramNodePlacement, type DiagramNodeRender, type DiagramUiState, FIBER_COLORS_12, type FiberCable, type FiberCableType, type FiberColorId, FiberEdge, FiberNode, FibreCableWithTubesExpanded, type FibreFlowCable, type FibreFlowCableKind, type FibreFlowCableNodeData, type FibreFlowCircuit, type FibreFlowClosure, type FibreFlowClosureNodeData, type FibreFlowEndpoint, FibreFlowMap, type FibreFlowMapProps, type FibreFlowSplice, FibreSplitNode, HANDLE_EXTENSION_PX, type MountClass, MultiTubeCableNode, NetworkDiagram, type NetworkDiagramFitViewOptions, type NetworkDiagramFlowMethods, type NetworkDiagramFlowObject, type NetworkDiagramOptions, type NetworkDiagramProps, type NetworkDiagramStoreApi, type NetworkDiagramToImageOptions, type NetworkEdge, type NetworkEdgeData, type NetworkGraphSnapshot, type NetworkNode, type NetworkNodeData, type NetworkNodeDataBase, type NetworkNodeDataByType, PANEL_BORDER_WIDTH, PANEL_HEADER_HEIGHT, PANEL_HEIGHT_PX, PANEL_PADDING, PANEL_TUBE_TRAY_SPACING, PANEL_WIDTH_PX, POWER_CONNECTORS, PatchPanelNode, type Port, type PortBlock, type PortCableType, type PortPosition, type PortType, PowerEdge, type PowerSide, RACK_HEADER_HEIGHT, RACK_WIDTH_PX, type RackConfig, type RackDevice, type RackDeviceType, type RackLayoutMode, type RackMountMode, RackNode, type RackSchemaOptions, type RawNetboxTemplate, type RawTemplatePort, type RawTemplatePortBlock, type ReplaceEdgeOptions, type SpliceConfig, SpliceNode, SplicePlacementError, type SplicePlacementValidation, type SpliceSchemaOptions, type SpliceTrayConfig, SpliceTrayNode, TEMPLATE_SCHEMA_VERSION, type TemplateFaceData, type TemplateFrontRearPortLink, type TemplateParseResult, type TemplatePort, type TemplatePortBlock, type TemplateSource, type TemplateValidationIssue, type TemplateValidationReport, type TemplateWidth, TubeNode, type UNumberingDirection, U_HEIGHT_PX, type ValidateConnectionParams, type ValidationResult, VerticalPDU, Width, addDeviceToRack, addSpliceToTray, baseColorFor, buildNodesFromRackConfig, buildNodesFromSpliceConfig, buildPortBlocksFromPorts, calculateClosureDimensions, calculateCouplerRightX, calculateCouplerSlotSpacing, calculateCouplerSpacing, calculateDevicePositionFromU, calculatePanelDimensions, calculateSlotPositionFromY, calculateSplicePositionFromNumber, calculateUPositions, calculateYFromSlotPosition, countTemplateFacePorts, createNetworkDiagramStore, createRackConfigFromNodes, createSpliceConfigFromNodes, diagramDocumentToNetworkGraph, fiberSolidOrStriped, findNearestRack, findNextAvailableHolderPosition, findNextAvailableUPosition, generateLayout, getConnectorConfig, getCouplerDimensions, getDefaultDeviceView, getDeviceConnectorType, getEndpointMetadata, getFiberColor, getFrontPortBlocks, getInnerContentWidth, getPDUPortType, getPanelHeight, getPanelWidth, getPowerPortStyle, getRackBounds, getRearPortBlocks, getResolvedPortBlocks, getStatusColor, getTrayDimensions, getTubeDimensions, hasFrontPorts, hasRearPorts, inventoryCableToNetworkEdge, inventoryDeviceToNetworkNode, inventoryRackToNetworkNode, inventoryToNetworkDiagram, isHighPowerConnector, isPointInRack, isStriped, isUPositionAvailable, netboxCableToNetworkEdge, netboxDeviceToNetworkNode, netboxRackToNetworkNode, netboxToNetworkDiagram, networkGraphToDiagramDocument, parseNetboxTemplate, removeDeviceFromRack, removeSpliceFromTray, replaceEdge, resolveEndpointCompatibilityKeys, snapToCouplerPosition, snapToSplicePosition, snapToUPosition, updateDeviceUPosition$1 as updateDeviceUPosition, updateDeviceUPosition as updateDeviceUPositionInSchema, updateSpliceHolderPosition, useEdges as useDiagramEdges, useNodes as useDiagramNodes, useNetworkDiagram, validateAndSnapDevice, validateRackDevicePlacements, validateRenderFidelity, validateSplicePlacements };
+export { type BuildPathLayoutOptions, COUPLERS_PER_PANEL, COUPLER_SLOT_HEIGHT_PX, COUPLER_WIDTH_PX, CableNode, ClosureNode, CouplerNode, DEFAULT_DIAGRAM_DIM_OPACITY, type DeviceFace, type DeviceImageFit, type DeviceImageOptions, type DeviceImageRepeat, DeviceNode, type DeviceNodeData, DevicePlacementError, type DevicePlacementValidation, type DevicePort, type DeviceStatus, type DeviceTemplateV2, type DiagramDocument, type DiagramEdge, type DiagramEdgeEndpoint, type DiagramEndpoint, DiagramErrorBoundary, type DiagramErrorBoundaryProps, type DiagramErrorBoundaryState, type DiagramExternalRef, type DiagramFocusOptions, type DiagramNode, type DiagramNodeKind, type DiagramNodePlacement, type DiagramNodeRender, type DiagramPortClickPayload, type DiagramPortContextValue, type DiagramPortHandleRef, DiagramPortProvider, type DiagramUiState, type EndpointConnectionKind, type EndpointMetadata, FIBER_COLORS_12, type FiberCable, type FiberCableType, type FiberColorId, FiberEdge, FiberNode, FibreCableWithTubesExpanded, type FibreCableWithTubesExpandedProps, type FibreFlowCable, type FibreFlowCableKind, type FibreFlowCableLayout, type FibreFlowCableNodeData, type FibreFlowCircuit, type FibreFlowClosure, type FibreFlowClosureNodeData, type FibreFlowColorMode, type FibreFlowEndpoint, type FibreFlowLayoutDirection, FibreFlowMap, type FibreFlowMapProps, type FibreFlowRow, type FibreFlowSplice, type FibreFlowTubeLabel, FibreSplitNode, HANDLE_EXTENSION_PX, type InventoryCableDTO, type InventoryDeviceDTO, type InventoryRackDTO, type ListPossiblePortHandleIdsOptions, type MountClass, MultiTubeCableNode, type NetBoxCable, type NetBoxDevice, type NetBoxDeviceTransformOptions, type NetBoxInterface, type NetBoxMappedPort, type NetBoxPortPosition, type NetBoxRack, NetworkDiagram, type NetworkDiagramActionPanelOptions, type NetworkDiagramFitViewOptions, type NetworkDiagramFlowMethods, type NetworkDiagramFlowObject, type NetworkDiagramInteractionOptions, type NetworkDiagramOptions, type NetworkDiagramProps, type NetworkDiagramState, type NetworkDiagramStore, type NetworkDiagramStoreApi, type NetworkDiagramStoreState, type NetworkDiagramToImageOptions, type NetworkDiagramValidateConnectionParams, type NetworkDiagramValidationResult, type NetworkEdge, type NetworkEdgeData, type NetworkEdgeType, type NetworkGraphSnapshot, type NetworkNode, type NetworkNodeData, type NetworkNodeDataBase, type NetworkNodeDataByType, type NetworkNodeType, PANEL_BORDER_WIDTH, PANEL_HEADER_HEIGHT, PANEL_HEIGHT_PX, PANEL_PADDING, PANEL_TUBE_TRAY_SPACING, PANEL_WIDTH_PX, POWER_CONNECTORS, PatchPanelNode, type PathLayoutDirection, type PathLayoutEdgeInput, type PathLayoutStepInput, type Port, type PortBlock, type PortCableType, type PortPosition, type PortType, type PortVisualDimensions, type PortVisualInput, type PortVisualKind, type PowerConnectorConfig, PowerEdge, type PowerPortStyle, type PowerSide, RACK_HEADER_HEIGHT, RACK_WIDTH_PX, type RackConfig, type RackDevice, type RackDeviceType, type RackLayoutMode, type RackMountMode, type RackMountedNodeType, RackNode, type RackNodeData, type RackNodeProps, type RackSchemaOptions, type RawNetboxTemplate, type RawTemplatePort, type RawTemplatePortBlock, type ReplaceEdgeOptions, type SpliceConfig, SpliceNode, SplicePlacementError, type SplicePlacementValidation, type SpliceSchemaOptions, type SpliceTrayConfig, SpliceTrayNode, TEMPLATE_SCHEMA_VERSION, type TemplateFaceData, type TemplateFrontRearPortLink, type TemplateParseResult, type TemplatePort, type TemplatePortBlock, type TemplateSource, type TemplateValidationIssue, type TemplateValidationReport, type TemplateWidth, TubeNode, type UNumberingDirection, U_HEIGHT_PX, type ValidateConnectionParams, type ValidationResult, VerticalPDU, Width, addDeviceToRack, addSpliceToTray, applyDeviceDisplayToNodes, applyDiagramFocusToEdges, applyDiagramFocusToNodes, baseColorFor, buildDevicePortGroupsFromPorts, buildNodesFromRackConfig, buildNodesFromSpliceConfig, buildPathLayoutGraph, buildPortBlocksFromPorts, buildPortHandleId, buildPortHandleId as buildReactNetworksHandleId, buildReactNetworksPortGroupsFromPorts, calculateClosureDimensions, calculateCouplerRightX, calculateCouplerSlotSpacing, calculateCouplerSpacing, calculateDevicePositionFromU, calculatePanelDimensions, calculateSlotPositionFromY, calculateSplicePositionFromNumber, calculateUPositions, calculateYFromSlotPosition, countTemplateFacePorts, createNetworkDiagramStore, createRackConfigFromNodes, createSpliceConfigFromNodes, diagramDocumentToNetworkGraph, fiberSolidOrStriped, findNearestRack, findNextAvailableHolderPosition, findNextAvailableUPosition, flattenDevicePortsFromGroups, flattenReactNetworksPortGroups, generateLayout, getConnectorConfig, getCouplerDimensions, getDefaultDeviceFace, getDeviceConnectorType, getEndpointMetadata, getFiberColor, getFrontPortBlocks, getInnerContentWidth, getPDUPortType, getPanelHeight, getPanelWidth, getPowerPortStyle, getRackBounds, getRearPortBlocks, getResolvedPortBlocks, getStandardPortVisualDimensions, getStatusColor, getTrayDimensions, getTubeDimensions, hasDiagramFocus, hasFrontPorts, hasRearPorts, inventoryCableToNetworkEdge, inventoryDeviceToNetworkNode, inventoryRackToNetworkNode, inventoryToDiagramDocument, inventoryToNetworkDiagram, isDeviceDiagramNode, isDiagramPortHandleHighlighted, isEdgeInDiagramFocus, isHighPowerConnector, isNodeInDiagramFocus, isPointInRack, isPowerPortType, isStriped, isUPositionAvailable, listPossiblePortHandleIds, looksLikePowerHandleId, netboxCableToNetworkEdge, netboxDeviceToNetworkNode, netboxRackToNetworkNode, netboxToDiagramDocument, netboxToNetworkDiagram, networkGraphToDiagramDocument, normalizeDevicePorts, normalizeDirectionalHandleId, normalizeHandleId, normalizePortPositionInput, normalizeReactNetworksPorts, parseNetboxTemplate, parseSemanticPortPosition, removeDeviceFromRack, removeSpliceFromTray, replaceEdge, resolveDevicePortBlocksFromFlatPorts, resolveDevicePortFace, resolveDevicePortGroup, resolveEndpointCompatibilityKeys, resolveNodeDevicePorts, resolvePortVisualKind, resolveReactNetworksNodePorts, resolveReactNetworksPortFace, resolveReactNetworksPortGroup, snapToCouplerPosition, snapToSplicePosition, snapToUPosition, updateDeviceUPosition$1 as updateDeviceUPosition, updateDeviceUPosition as updateDeviceUPositionInSchema, updateSpliceHolderPosition, useEdges as useDiagramEdges, useNodes as useDiagramNodes, useDiagramPortInteraction, useNetworkDiagram, validateAndSnapDevice, validatePortHandleOnNodeData, validateRackDevicePlacements, validateRenderFidelity, validateSplicePlacements };