@mp70/react-networks 0.1.8-alpha → 0.1.9-beta

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-import React$1 from 'react';
-import { NodeProps, EdgeProps, Edge, Connection } from 'reactflow';
+import React$1, { Component, ReactNode, ErrorInfo } from 'react';
+import { NodeTypes, EdgeTypes, Connection, Edge, ConnectionMode, FitViewOptions, NodeProps, EdgeProps } from 'reactflow';
 
 /**
  * Rack device width configuration
  * @public
  */
+
 declare enum Width {
     /** Full width device (19" rack width) */
     FULL = "full",
@@ -15,13 +16,18 @@ declare enum Width {
  * Port configuration for network devices
  * @public
  */
+/**
+ * Port type enumeration
+ * @public
+ */
+type PortType = 'ethernet' | 'fiber' | 'console' | 'mgmt' | 'usb' | 'power_ac' | 'power_c13' | 'power_c19';
 interface Port {
     /** Display label for the port */
     label: string;
     /** Whether the port is currently connected */
     connected: boolean;
     /** Type of port for styling and validation */
-    type?: 'ethernet' | 'fiber' | 'console' | 'mgmt' | 'usb' | 'power_ac' | 'power_c13' | 'power_c19';
+    type?: PortType;
     /** Cable type for connection validation */
     cableType?: 'smf' | 'cat6' | 'om3' | 'om4' | 'om5' | 'cat5e' | 'cat6a' | 'cat7' | 'fiber' | 'ethernet';
 }
@@ -39,7 +45,7 @@ interface PortBlock {
  * Network node types supported by the diagram
  * @public
  */
-type NetworkNodeType = 'rack' | 'switch' | 'router' | 'server' | 'fiber' | 'patch-panel' | 'device' | 'vertical-pdu' | 'splice' | 'splice-tray' | 'tube' | 'cable' | 'coupler' | 'closure';
+type NetworkNodeType = 'rack' | 'switch' | 'router' | 'server' | 'fiber' | 'patch-panel' | 'device' | 'vertical-pdu' | 'splice' | 'splice-tray' | 'tube' | 'cable' | 'multi-tube-cable' | 'coupler' | 'closure' | 'fibre-split' | 'fibre-flow-cable' | 'fibre-flow-closure';
 /**
  * Device status states
  * @public
@@ -110,6 +116,16 @@ interface NetworkNode {
         rearPorts?: PortBlock[];
         /** Power port side for rear view */
         powerSide?: PowerSide;
+        /** Optional front image URL for device background */
+        frontImageUrl?: string;
+        /** Optional rear image URL for device background */
+        rearImageUrl?: string;
+        /** Optional background sizing for device images */
+        imageFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+        /** Optional background position for device images */
+        imagePosition?: string;
+        /** Optional background repeat for device images */
+        imageRepeat?: 'no-repeat' | 'repeat' | 'repeat-x' | 'repeat-y';
         /** Vertical PDU height in centimeters */
         heightCm?: number;
         /** Number of AC power ports */
@@ -136,12 +152,20 @@ interface NetworkNode {
         panelWidth?: number;
         /** Height override for container nodes (patch-panel, closure) */
         panelHeight?: number;
+        /** Optional rack width in pixels (for rack nodes, default: 300px) */
+        rackWidthPx?: number;
         /** Number of rows for container nodes (patch-panel, closure) */
         rows?: number;
         /** Number of columns for container nodes (patch-panel, closure) */
         cols?: number;
         /** Header text for container nodes */
         header?: string;
+        /** Type of fibre splitter: 'splitter' or 'WDM' (default: 'splitter') */
+        splitterType?: 'splitter' | 'WDM';
+        /** Number of input fibers on the left (1 or 2, default: 1) */
+        inputCount?: number;
+        /** Number of output fibers on the right (1-64, default: 8) */
+        outputCount?: number;
         /** Additional custom properties */
         [key: string]: any;
     };
@@ -150,7 +174,7 @@ interface NetworkNode {
  * Network edge types
  * @public
  */
-type NetworkEdgeType = 'fiber' | 'ethernet' | 'power' | 'smoothstep' | 'step' | 'thick-cable';
+type NetworkEdgeType = 'fiber' | 'ethernet' | 'power' | 'smoothstep' | 'step' | 'thick-cable' | 'fibre-flow' | 'fibre-flow-link';
 /**
  * Network edge data structure
  * @public
@@ -178,6 +202,18 @@ interface NetworkEdge {
         color?: string;
         /** Edge kind for styling/validation */
         kind?: 'fiber' | 'power' | 'network';
+        /** Whether this edge represents a ribbon fiber connection */
+        isRibbon?: boolean;
+        /** Array of fiber IDs for ribbon mode (6-12 fibers) */
+        ribbonFiberIds?: number[];
+        /** Highlight edge with a pulsing stroke */
+        highlight?: boolean;
+        /** Override highlight color (defaults to edge color) */
+        highlightColor?: string;
+        /** Override highlight max stroke width */
+        highlightWidth?: number;
+        /** Optional tag for grouping edges in demos */
+        traceTag?: string;
         /** Additional custom properties */
         [key: string]: any;
     };
@@ -209,6 +245,8 @@ interface RackConfig {
     customHeaderText?: string;
     /** Devices mounted in the rack */
     devices: RackDevice[];
+    /** Optional rack width in pixels (default: 300px which represents standard 48.26cm/19" rack) */
+    rackWidthPx?: number;
 }
 /**
  * Device mounted in a rack
@@ -235,6 +273,16 @@ interface RackDevice {
     rearPorts?: PortBlock[];
     /** Power port side for rear view */
     powerSide?: PowerSide;
+    /** Optional front image URL for device background */
+    frontImageUrl?: string;
+    /** Optional rear image URL for device background */
+    rearImageUrl?: string;
+    /** Optional background sizing for device images */
+    imageFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+    /** Optional background position for device images */
+    imagePosition?: string;
+    /** Optional background repeat for device images */
+    imageRepeat?: 'no-repeat' | 'repeat' | 'repeat-x' | 'repeat-y';
     /** Connected device IDs */
     connections?: string[];
 }
@@ -279,6 +327,10 @@ interface SpliceConfig {
     holder: number;
     /** Loss value in dB */
     lossDb?: number;
+    /** Splice mode: 'single' for individual fiber, 'ribbon' for ribbon splices */
+    mode?: 'single' | 'ribbon';
+    /** For ribbon mode: array of fiber IDs (6-12) in the ribbon */
+    ribbonFiberIds?: number[];
 }
 /**
  * Splice tray configuration structure
@@ -322,6 +374,18 @@ interface NetworkDiagramProps {
     onNodeClick?: (node: NetworkNode | null) => void;
     /** Callback when an edge is clicked */
     onEdgeClick?: (edge: NetworkEdge) => void;
+    /** Custom React Flow node types to merge with defaults */
+    nodeTypes?: NodeTypes;
+    /** Custom React Flow edge types to merge with defaults */
+    edgeTypes?: EdgeTypes;
+    /** Optional onConnect override (React Flow connection handler) */
+    onConnect?: (connection: Connection) => void;
+    /** Optional onEdgeUpdate override */
+    onEdgeUpdate?: (oldEdge: Edge, newConnection: Connection) => void;
+    /** Optional isValidConnection override */
+    isValidConnection?: (connection: Connection) => boolean;
+    /** Optional connection mode override */
+    connectionMode?: ConnectionMode;
     /** Callback when device view changes */
     onViewChange?: (nodeId: string, view: DeviceView) => void;
     /** Callback when rack face changes */
@@ -343,6 +407,9 @@ interface NetworkDiagramProps {
         setNodes: (nodes: any[]) => void;
         setEdges: (edges: any[]) => void;
         toImage: (options?: any) => Promise<string>;
+        getNodes: () => any[];
+        getEdges: () => any[];
+        fitView: (options?: any) => void;
     }) => void;
     /** Show download button */
     showDownloadButton?: boolean;
@@ -352,31 +419,175 @@ interface NetworkDiagramProps {
     downloadButtonText?: string;
     /** Download button styling options */
     downloadButtonStyle?: React.CSSProperties;
-    /** Allow reconnecting existing edges from either end */
-    allowReconnectExisting?: boolean;
     /** Use smoothstep edges for tube connections (both tube-to-cable and cable-to-tube). Default is fiber. */
     useSmoothstepEdgesForTubes?: boolean;
     /** 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;
 }
 
+/**
+ * Main component for rendering interactive network diagrams.
+ *
+ * The NetworkDiagram component provides a complete solution for visualizing
+ * network infrastructure including racks, devices, fiber connections, and power distribution.
+ *
+ * @example
+ * ```tsx
+ * import { NetworkDiagram, NetworkNode, NetworkEdge } from '@mp70/react-networks';
+ *
+ * const nodes: NetworkNode[] = [
+ *   {
+ *     id: 'rack-1',
+ *     type: 'rack',
+ *     position: { x: 100, y: 100 },
+ *     data: { label: 'Main Rack', uHeight: 42 }
+ *   }
+ * ];
+ *
+ * <NetworkDiagram nodes={nodes} edges={[]} />
+ * ```
+ *
+ * @public
+ */
 declare const NetworkDiagram: React$1.FC<NetworkDiagramProps>;
 
+interface DiagramErrorBoundaryProps {
+    /** Content to render when an error is caught */
+    children: ReactNode;
+    /** Optional fallback UI when an error occurs (default: simple message) */
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /** Optional callback when an error is caught (e.g. for logging) */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface State {
+    error: Error | null;
+}
+/**
+ * Error boundary that catches errors in the diagram tree (e.g. React Flow,
+ * custom nodes) and renders a fallback instead of crashing the whole app.
+ * Wrap &lt;NetworkDiagram&gt; (or the diagram subtree) with this for production.
+ *
+ * @example
+ * ```tsx
+ * <DiagramErrorBoundary
+ *   fallback={(error, reset) => (
+ *     <div>
+ *       <p>Diagram failed: {error.message}</p>
+ *       <button onClick={reset}>Try again</button>
+ *     </div>
+ *   )}
+ *   onError={(err, info) => logToService(err, info)}
+ * >
+ *   <NetworkDiagram nodes={nodes} edges={edges} />
+ * </DiagramErrorBoundary>
+ * ```
+ */
+declare class DiagramErrorBoundary extends Component<DiagramErrorBoundaryProps, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+
 interface RackNodeProps extends NodeProps<NetworkNode['data']> {
     onViewChange?: (nodeId: string, view: '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>;
 
 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']> & {
     className?: string;
 }>;
 
 declare const PowerEdge: React$1.FC<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: [{
+ *       name: 'Network Ports',
+ *       ports: [
+ *         { label: 'eth0', connected: true, type: 'ethernet' }
+ *       ]
+ *     }]
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 declare const DeviceNode: React$1.FC<NodeProps<NetworkNode['data']>>;
 
 declare const VerticalPDU: React$1.FC<NodeProps<NetworkNode['data']>>;
@@ -399,18 +610,133 @@ declare const TubeNode: React$1.FC<NodeProps<NetworkNode['data']>>;
 
 /**
  * CableNode
- * - Visually mirrors TubeNode but represents an entire cable
- * - Each colored handle corresponds to a tube within the cable
+ * - Represents a multi-fiber cable (1-24 fibers)
+ * - Each colored handle corresponds to a single fiber
  * - Displays cable summary text (fiber count + cable identifier)
  */
 declare const CableNode: React$1.FC<NodeProps<NetworkNode['data']>>;
 
+/**
+ * MultiTubeCableNode
+ * - Represents a multi-tube cable (1-24 tubes)
+ * - Each colored handle corresponds to a tube within the cable
+ * - Displays cable summary text (fiber count + cable identifier)
+ */
+declare const MultiTubeCableNode: React$1.FC<NodeProps<NetworkNode['data']>>;
+
 declare const CouplerNode: React$1.FC<NodeProps<NetworkNode['data']>>;
 
 declare const PatchPanelNode: React$1.FC<NodeProps<NetworkNode['data']>>;
 
 declare const ClosureNode: React$1.FC<NodeProps<NetworkNode['data']>>;
 
+/**
+ * FibreSplitNode component for rendering fiber splitters and WDM devices
+ * Uses a trapezoid shape pointing right (narrow input on left, wider outputs on right)
+ *
+ * @public
+ */
+declare const FibreSplitNode: React$1.FC<NodeProps<NetworkNode['data']>>;
+
+type FibreFlowCableKind = 'simple' | 'tube';
+interface FibreFlowEndpoint {
+    tube?: number;
+    fiber: number;
+}
+interface FibreFlowSplice {
+    id: string;
+    from: FibreFlowEndpoint;
+    to: FibreFlowEndpoint;
+    lossDb?: number;
+    circuitId?: string;
+    label?: string;
+    color?: string;
+}
+interface FibreFlowCable {
+    id: string;
+    label: string;
+    kind?: FibreFlowCableKind;
+    fiberCount?: number;
+    tubeCount?: number;
+    fibersPerTube?: number;
+    tubeStartIndex?: number;
+    fiberStartIndex?: number;
+    tubeColorMap?: Record<number, string>;
+    jacketColor?: string;
+    distanceLabel?: string;
+    distanceMeters?: number;
+}
+interface FibreFlowClosure {
+    id: string;
+    chamberId?: string;
+    leftCable: FibreFlowCable;
+    rightCable: FibreFlowCable;
+    splices: FibreFlowSplice[];
+}
+interface FibreFlowCircuit {
+    id: string;
+    label: string;
+    color?: string;
+}
+
+type FibreFlowLayoutDirection = 'horizontal' | 'vertical';
+type FibreFlowColorMode = 'dark' | 'light';
+interface FibreFlowMapProps {
+    closures: FibreFlowClosure[];
+    circuits?: FibreFlowCircuit[];
+    highlightedCircuitId?: string;
+    layout?: FibreFlowLayoutDirection;
+    rowHeight?: number;
+    tubeGap?: number;
+    closureGap?: number;
+    cableColumnWidth?: number;
+    spliceAreaWidth?: number;
+    showTubeLabels?: boolean;
+    showFiberNumbers?: boolean;
+    colorMode?: FibreFlowColorMode;
+    showCircuitId?: boolean;
+    className?: string;
+    style?: React$1.CSSProperties;
+    panOnDrag?: boolean;
+    panOnScroll?: boolean;
+    zoomOnScroll?: boolean;
+}
+declare const FibreFlowMap: React$1.FC<FibreFlowMapProps>;
+
+interface FibreFlowRow {
+    key: string;
+    tubeIndex?: number;
+    fiberIndex: number;
+    y: number;
+    color: string;
+    striped: boolean;
+    backgroundImage?: string;
+}
+interface FibreFlowTubeLabel {
+    tubeIndex: number;
+    y: number;
+    label: string;
+    color: string;
+}
+interface FibreFlowCableLayout {
+    rows: FibreFlowRow[];
+    tubeLabels: FibreFlowTubeLabel[];
+    height: number;
+}
+
+interface FibreCableWithTubesExpandedProps {
+    cable: FibreFlowCable;
+    side: 'left' | 'right';
+    rowHeight?: number;
+    tubeGap?: number;
+    columnWidth?: number;
+    layout?: FibreFlowCableLayout;
+    showTubeLabels?: boolean;
+    showFiberNumbers?: boolean;
+    showCableLabel?: boolean;
+}
+declare const FibreCableWithTubesExpanded: React$1.FC<FibreCableWithTubesExpandedProps>;
+
 interface InventoryRackDTO {
     id: string | number;
     name: string;
@@ -571,6 +897,8 @@ declare const snapToSplicePosition: (splice: NetworkNode, tray: NetworkNode, new
 declare const findNextAvailableHolderPosition: (tray: NetworkNode, splice: NetworkNode, allNodes: NetworkNode[], startFrom?: number) => number;
 /**
  * Calculate splice position based on holder number within a tray
+ * Note: This function doesn't have access to splice data, so it uses single mode spacing
+ * For ribbon splices, use calculateSplicePositionFromNumberWithData instead
  */
 declare const calculateSplicePositionFromNumber: (tray: NetworkNode, holderPosition: number) => {
     x: number;
@@ -615,6 +943,17 @@ declare const PANEL_PADDING = 8;
 declare const PANEL_TUBE_TRAY_SPACING = 120;
 /**
  * Calculate coupler dimensions based on node data
+ *
+ * @param node - The coupler node with optional couplerFiberCount in data
+ * @returns Object with width and height in pixels
+ * @public
+ *
+ * @example
+ * ```ts
+ * const node = { type: 'coupler', data: { couplerFiberCount: 2 } };
+ * const dims = getCouplerDimensions(node);
+ * // Returns: { width: 80, height: 30 }
+ * ```
  */
 declare function getCouplerDimensions(node: NetworkNode): {
     width: number;
@@ -622,6 +961,17 @@ declare function getCouplerDimensions(node: NetworkNode): {
 };
 /**
  * Calculate tube dimensions based on node data
+ *
+ * @param node - The tube node with optional fibersPerTube in data (default: 12)
+ * @returns Object with width and height in pixels
+ * @public
+ *
+ * @example
+ * ```ts
+ * const node = { type: 'tube', data: { fibersPerTube: 12 } };
+ * const dims = getTubeDimensions(node);
+ * // Returns: { width: calculated, height: 20 }
+ * ```
  */
 declare function getTubeDimensions(node: NetworkNode): {
     width: number;
@@ -629,6 +979,12 @@ declare function getTubeDimensions(node: NetworkNode): {
 };
 /**
  * Get tray dimensions
+ *
+ * Tray dimensions are fixed and do not depend on node data.
+ *
+ * @param _node - The tray node (unused, dimensions are fixed)
+ * @returns Object with fixed width (TRAY_WIDTH_PX) and height (0)
+ * @public
  */
 declare function getTrayDimensions(_node: NetworkNode): {
     width: number;
@@ -636,30 +992,73 @@ declare function getTrayDimensions(_node: NetworkNode): {
 };
 /**
  * Calculate panel width based on content
+ *
+ * @param panelNode - The panel node with optional panelWidth in data
+ * @returns Panel width in pixels, or default PANEL_WIDTH_PX if not specified
+ * @public
  */
 declare function getPanelWidth(panelNode: NetworkNode): number;
 /**
  * Calculate panel height based on content
+ *
+ * @param panelNode - The panel node with optional panelHeight in data
+ * @returns Panel height in pixels, or default PANEL_HEIGHT_PX if not specified
+ * @public
  */
 declare function getPanelHeight(panelNode: NetworkNode): number;
 /**
  * Get inner content width (panel width minus borders/padding)
+ *
+ * Calculates the usable width inside a panel after accounting for borders and padding.
+ *
+ * @param panelNode - The panel node
+ * @returns Inner content width in pixels
+ * @public
  */
 declare function getInnerContentWidth(panelNode: NetworkNode): number;
 /**
  * Calculate coupler right X position
+ *
+ * Calculates the X position for the right edge of a coupler within a panel.
+ *
+ * @param panelNode - The panel node containing the coupler
+ * @param couplerWidth - Width of the coupler in pixels
+ * @returns X position for the right edge of the coupler
+ * @public
  */
 declare function calculateCouplerRightX(panelNode: NetworkNode, couplerWidth: number): number;
 /**
  * Calculate slot position from Y coordinate
+ *
+ * Converts a Y pixel coordinate to a slot number (1-indexed).
+ *
+ * @param y - Y coordinate in pixels
+ * @param slotHeight - Height of each slot in pixels (default: COUPLER_SLOT_HEIGHT_PX)
+ * @returns Slot position (1-indexed)
+ * @public
  */
 declare function calculateSlotPositionFromY(y: number, slotHeight?: number): number;
 /**
  * Calculate Y coordinate from slot position
+ *
+ * Converts a slot number (1-indexed) to a Y pixel coordinate.
+ *
+ * @param slot - Slot position (1-indexed)
+ * @param slotHeight - Height of each slot in pixels (default: COUPLER_SLOT_HEIGHT_PX)
+ * @returns Y coordinate in pixels
+ * @public
  */
 declare function calculateYFromSlotPosition(slot: number, slotHeight?: number): number;
 /**
  * Snap coupler to nearest slot position
+ *
+ * Snaps a coupler's position to the nearest valid slot within a panel.
+ *
+ * @param coupler - The coupler node to snap
+ * @param panel - The panel node containing the coupler
+ * @param position - Current position { x, y }
+ * @returns Snapped position with optional slotPosition
+ * @public
  */
 declare function snapToCouplerPosition(coupler: NetworkNode, panel: NetworkNode, position: {
     x: number;
@@ -671,6 +1070,21 @@ declare function snapToCouplerPosition(coupler: NetworkNode, panel: NetworkNode,
 };
 /**
  * Calculate panel dimensions based on child nodes
+ *
+ * Automatically calculates the width and height of a panel based on its child nodes.
+ * Supports special layouts for patch panels with tubes, trays, and couplers.
+ *
+ * @param panelNode - The panel node
+ * @param childNodes - Array of child nodes within the panel
+ * @returns Object with calculated width and height in pixels
+ * @public
+ *
+ * @example
+ * ```ts
+ * const panel = { id: 'panel-1', type: 'patch-panel', data: {} };
+ * const children = [tubeNode, trayNode, couplerNode];
+ * const dims = calculatePanelDimensions(panel, children);
+ * ```
  */
 declare function calculatePanelDimensions(panelNode: NetworkNode, childNodes: NetworkNode[]): {
     width: number;
@@ -678,10 +1092,27 @@ declare function calculatePanelDimensions(panelNode: NetworkNode, childNodes: Ne
 };
 /**
  * Calculate spacing between couplers
+ *
+ * Calculates the vertical spacing needed between couplers to fit them evenly
+ * within the available height.
+ *
+ * @param numCouplers - Number of couplers to space
+ * @param couplerHeight - Height of each coupler in pixels
+ * @param availableHeight - Total available height in pixels
+ * @returns Spacing between couplers in pixels (includes coupler height)
+ * @public
  */
 declare function calculateCouplerSpacing(numCouplers: number, couplerHeight: number, availableHeight: number): number;
 /**
  * Calculate coupler slot spacing
+ *
+ * Alias for calculateCouplerSpacing. Calculates spacing between coupler slots.
+ *
+ * @param numCouplers - Number of couplers to space
+ * @param couplerHeight - Height of each coupler in pixels
+ * @param availableHeight - Total available height in pixels
+ * @returns Spacing between coupler slots in pixels
+ * @public
  */
 declare function calculateCouplerSlotSpacing(numCouplers: number, couplerHeight: number, availableHeight: number): number;
 
@@ -727,10 +1158,57 @@ interface DevicePlacementValidation {
 }
 /**
  * Validate device placements within a rack schema
+ *
+ * Checks for out-of-bounds placements and device-to-device conflicts.
+ * Uses the generic validatePlacements utility for consistent validation logic.
+ *
+ * @param rack - The rack configuration to validate
+ * @param _options - Validation options (currently unused)
+ * @returns Validation result with conflicts and out-of-bounds errors
+ * @public
+ *
+ * @example
+ * ```ts
+ * const rack: RackConfig = {
+ *   id: 'rack-1',
+ *   units: 42,
+ *   devices: [
+ *     { id: 'dev-1', unit: 1, height: 2, ... },
+ *     { id: 'dev-2', unit: 2, height: 1, ... } // Conflicts with dev-1
+ *   ]
+ * };
+ * const result = validateRackDevicePlacements(rack);
+ * if (!result.isValid) {
+ *   console.log('Conflicts:', result.conflicts);
+ * }
+ * ```
  */
 declare function validateRackDevicePlacements(rack: RackConfig, _options?: RackSchemaOptions): DevicePlacementValidation;
 /**
  * Build NetworkNode array from RackConfig array with comprehensive validation
+ *
+ * Converts rack configurations to React Flow nodes with automatic validation
+ * and conflict resolution. Supports strict and nearest conflict policies.
+ *
+ * @param racks - Array of rack configurations
+ * @param options - Build options including conflict policy and validation settings
+ * @returns Array of NetworkNode objects ready for React Flow
+ * @throws {DevicePlacementError} If validation fails in strict mode
+ * @public
+ *
+ * @example
+ * ```ts
+ * const racks: RackConfig[] = [{
+ *   id: 'rack-1',
+ *   name: 'Main Rack',
+ *   units: 42,
+ *   devices: [...]
+ * }];
+ * const nodes = buildNodesFromRackConfig(racks, {
+ *   conflictPolicy: 'strict',
+ *   validatePlacements: true
+ * });
+ * ```
  */
 declare function buildNodesFromRackConfig(racks: RackConfig[], options?: RackSchemaOptions): NetworkNode[];
 /**
@@ -787,10 +1265,55 @@ interface SplicePlacementValidation {
 }
 /**
  * Validate splice placements within a tray schema
+ *
+ * Checks for out-of-bounds placements and splice-to-splice conflicts.
+ * Uses the generic validatePlacements utility for consistent validation logic.
+ *
+ * @param tray - The splice tray configuration to validate
+ * @param _options - Validation options (currently unused)
+ * @returns Validation result with conflicts and out-of-bounds errors
+ * @public
+ *
+ * @example
+ * ```ts
+ * const tray: SpliceTrayConfig = {
+ *   id: 'tray-1',
+ *   splices: [
+ *     { id: 'splice-1', holder: 1, ... },
+ *     { id: 'splice-2', holder: 1, ... } // Conflicts with splice-1
+ *   ]
+ * };
+ * const result = validateSplicePlacements(tray);
+ * if (!result.isValid) {
+ *   console.log('Conflicts:', result.conflicts);
+ * }
+ * ```
  */
 declare function validateSplicePlacements(tray: SpliceTrayConfig, _options?: SpliceSchemaOptions): SplicePlacementValidation;
 /**
  * Build NetworkNode array from SpliceTrayConfig array with comprehensive validation
+ *
+ * Converts splice tray configurations to React Flow nodes with automatic validation
+ * and conflict resolution. Supports strict and nearest conflict policies.
+ *
+ * @param trays - Array of splice tray configurations
+ * @param options - Build options including conflict policy and validation settings
+ * @returns Array of NetworkNode objects ready for React Flow
+ * @throws {SplicePlacementError} If validation fails in strict mode
+ * @public
+ *
+ * @example
+ * ```ts
+ * const trays: SpliceTrayConfig[] = [{
+ *   id: 'tray-1',
+ *   name: 'Tray 1',
+ *   splices: [...]
+ * }];
+ * const nodes = buildNodesFromSpliceConfig(trays, {
+ *   conflictPolicy: 'strict',
+ *   validatePlacements: true
+ * });
+ * ```
  */
 declare function buildNodesFromSpliceConfig(trays: SpliceTrayConfig[], options?: SpliceSchemaOptions): NetworkNode[];
 /**
@@ -939,6 +1462,15 @@ declare function findNearestRack(point: {
     y: number;
 }, racks: NetworkNode[]): NetworkNode | null;
 
+declare const U_HEIGHT_PX = 20;
+declare const RACK_HEADER_HEIGHT = 60;
+declare const RACK_WIDTH_PX = 300;
+/**
+ * Handle extension in pixels - handles extend this many pixels outside nodes
+ * Used in dimension calculations for panels and closures
+ */
+declare const HANDLE_EXTENSION_PX = 5;
+
 /**
  * Options for replacing an edge in the edges array
  */
@@ -998,4 +1530,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, DeviceNode, DevicePlacementError, type DevicePlacementValidation, FIBER_COLORS_12, type FiberCable, type FiberColorId, FiberEdge, FiberNode, NetworkDiagram, type NetworkDiagramProps, type NetworkEdge, type NetworkNode, 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, PowerEdge, type RackConfig, type RackDevice, RackNode, type RackSchemaOptions, type ReplaceEdgeOptions, type SpliceConfig, SpliceNode, SplicePlacementError, type SplicePlacementValidation, type SpliceSchemaOptions, type SpliceTrayConfig, SpliceTrayNode, TubeNode, VerticalPDU, Width, addDeviceToRack, addSpliceToTray, baseColorFor, buildNodesFromRackConfig, buildNodesFromSpliceConfig, calculateCouplerRightX, calculateCouplerSlotSpacing, calculateCouplerSpacing, calculateDevicePositionFromU, calculatePanelDimensions, calculateSlotPositionFromY, calculateSplicePositionFromNumber, calculateYFromSlotPosition, createNetworkDiagramStore, createRackConfigFromNodes, createSpliceConfigFromNodes, fiberSolidOrStriped, findNearestRack, findNextAvailableHolderPosition, findNextAvailableUPosition, generateLayout, getConnectorConfig, getCouplerDimensions, getDeviceConnectorType, getFiberColor, getInnerContentWidth, getPDUPortType, getPanelHeight, getPanelWidth, getPowerPortStyle, getRackBounds, getStatusColor, getTrayDimensions, getTubeDimensions, inventoryCableToNetworkEdge, inventoryDeviceToNetworkNode, inventoryRackToNetworkNode, inventoryToNetworkDiagram, isHighPowerConnector, isPointInRack, isStriped, isUPositionAvailable, removeDeviceFromRack, removeSpliceFromTray, replaceEdge, snapToCouplerPosition, snapToSplicePosition, snapToUPosition, updateDeviceUPosition$1 as updateDeviceUPosition, updateDeviceUPosition as updateDeviceUPositionInSchema, updateSpliceHolderPosition, useEdges as useDiagramEdges, useNodes as useDiagramNodes, useNetworkDiagram, validateAndSnapDevice, validateRackDevicePlacements, validateSplicePlacements };
+export { COUPLERS_PER_PANEL, COUPLER_SLOT_HEIGHT_PX, COUPLER_WIDTH_PX, CableNode, ClosureNode, CouplerNode, DeviceNode, DevicePlacementError, type DevicePlacementValidation, DiagramErrorBoundary, type DiagramErrorBoundaryProps, FIBER_COLORS_12, type FiberCable, type FiberColorId, FiberEdge, FiberNode, FibreCableWithTubesExpanded, type FibreFlowCable, type FibreFlowCableKind, type FibreFlowCircuit, type FibreFlowClosure, type FibreFlowEndpoint, FibreFlowMap, type FibreFlowMapProps, type FibreFlowSplice, FibreSplitNode, HANDLE_EXTENSION_PX, MultiTubeCableNode, NetworkDiagram, type NetworkDiagramProps, type NetworkEdge, type NetworkNode, 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 PortType, PowerEdge, RACK_HEADER_HEIGHT, RACK_WIDTH_PX, type RackConfig, type RackDevice, RackNode, type RackSchemaOptions, type ReplaceEdgeOptions, type SpliceConfig, SpliceNode, SplicePlacementError, type SplicePlacementValidation, type SpliceSchemaOptions, type SpliceTrayConfig, SpliceTrayNode, TubeNode, U_HEIGHT_PX, VerticalPDU, Width, addDeviceToRack, addSpliceToTray, baseColorFor, buildNodesFromRackConfig, buildNodesFromSpliceConfig, calculateCouplerRightX, calculateCouplerSlotSpacing, calculateCouplerSpacing, calculateDevicePositionFromU, calculatePanelDimensions, calculateSlotPositionFromY, calculateSplicePositionFromNumber, calculateYFromSlotPosition, createNetworkDiagramStore, createRackConfigFromNodes, createSpliceConfigFromNodes, fiberSolidOrStriped, findNearestRack, findNextAvailableHolderPosition, findNextAvailableUPosition, generateLayout, getConnectorConfig, getCouplerDimensions, getDeviceConnectorType, getFiberColor, getInnerContentWidth, getPDUPortType, getPanelHeight, getPanelWidth, getPowerPortStyle, getRackBounds, getStatusColor, getTrayDimensions, getTubeDimensions, inventoryCableToNetworkEdge, inventoryDeviceToNetworkNode, inventoryRackToNetworkNode, inventoryToNetworkDiagram, isHighPowerConnector, isPointInRack, isStriped, isUPositionAvailable, removeDeviceFromRack, removeSpliceFromTray, replaceEdge, snapToCouplerPosition, snapToSplicePosition, snapToUPosition, updateDeviceUPosition$1 as updateDeviceUPosition, updateDeviceUPosition as updateDeviceUPositionInSchema, updateSpliceHolderPosition, useEdges as useDiagramEdges, useNodes as useDiagramNodes, useNetworkDiagram, validateAndSnapDevice, validateRackDevicePlacements, validateSplicePlacements };