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

package/dist/index.d.ts

@@ -253,7 +253,7 @@ type PortCableType = 'smf' | 'cat6' | 'om3' | 'om4' | 'om5' | 'cat5e' | 'cat6a'
  *
  * @public
  */
-type DeviceImageFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+type DeviceImageFit = 'cover' | 'contain' | 'contain-height' | 'fill' | 'none' | 'scale-down';
 /**
  * Device image repeat options.
  * @public
@@ -298,8 +298,9 @@ interface PortPosition {
     yPercent?: number;
 }
 /**
- * Simplified flat port input for device and PDU rendering.
- * `react-networks` groups these into front/rear `PortBlock[]` internally.
+ * Recommended simple port input for device and PDU rendering.
+ * Pass a flat array in `ports`; `react-networks` groups entries into front/rear
+ * `PortBlock[]` internally using each port's `face` and `group`.
  * @public
  */
 interface DevicePort {
@@ -319,6 +320,8 @@ interface DevicePort {
     cableType?: PortCableType;
     /** Optional power connector type for rendering (mainly for PDU ports) */
     connectorType?: 'C13' | 'C14' | 'C19' | 'C20';
+    /** Optional compatibility keys. When omitted, defaults are derived from type/cable/connector data. */
+    compatibility?: string[];
     /** Optional sort order within a face/group bucket */
     order?: number;
     /**
@@ -341,6 +344,8 @@ interface Port {
     cableType?: PortCableType;
     /** Optional power connector type for rendering (mainly for PDU ports) */
     connectorType?: 'C13' | 'C14' | 'C19' | 'C20';
+    /** Optional compatibility keys. When omitted, defaults are derived from type/cable/connector data. */
+    compatibility?: string[];
     /** Optional explicit handle placement */
     position?: PortPosition;
 }
@@ -399,11 +404,11 @@ interface NetworkNodeDataBase extends DeviceImageOptions {
     label: string;
     /** Current status of the node/device */
     status?: DeviceStatus | string;
-    /** Flat port input that is normalized into grouped front/rear blocks internally */
+    /** Simple flat port input. Use `portGroups` / `rearPortGroups` for explicit grouped control. */
     ports?: DevicePort[] | number;
-    /** Lower-level grouped front port input */
+    /** Advanced grouped front port input */
     portGroups?: PortBlock[];
-    /** Lower-level grouped rear port input */
+    /** Advanced grouped rear port input */
     rearPortGroups?: PortBlock[];
     /** List of connected node IDs */
     connections?: string[];
@@ -419,6 +424,8 @@ interface NetworkNodeDataBase extends DeviceImageOptions {
     uHeight?: number;
     /** Device position within rack in U units */
     uPosition?: number;
+    /** Whether this node is currently mounted inside a rack container */
+    isRackMounted?: boolean;
     /** Current front/rear view orientation */
     view?: DeviceView;
     /** Rack face orientation */
@@ -701,9 +708,148 @@ type NetworkEdge<TData extends NetworkEdgeData = NetworkEdgeData> = {
     targetHandle?: string;
     /** Type of network connection */
     type?: NetworkEdgeType;
+    /** Whether the edge should be hidden from rendering */
+    hidden?: boolean;
     /** Edge data and configuration */
     data?: TData;
 };
+/**
+ * High-level document format independent from React Flow handle ids.
+ * @public
+ */
+interface DiagramDocument {
+    nodes: DiagramNode[];
+    edges: DiagramEdge[];
+    ui?: DiagramUiState;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Node kinds used by the document model.
+ * @public
+ */
+type DiagramNodeKind = 'rack' | 'equipment' | 'pdu' | 'fiber' | 'tube' | 'cable' | 'multi-tube-cable' | 'splice' | 'coupler' | 'splitter' | 'container' | 'fibre-flow-cable' | 'fibre-flow-closure';
+/**
+ * Placement data for document nodes.
+ * @public
+ */
+interface DiagramNodePlacement {
+    position: {
+        x: number;
+        y: number;
+    };
+    parentId?: string;
+    extent?: 'parent';
+    rack?: {
+        uPosition?: number;
+        mountMode?: RackMountMode;
+        rackLayout?: RackLayoutMode;
+        rackWidthPx?: number;
+        rackFaceGapPx?: number;
+    };
+    container?: {
+        slotPosition?: number;
+        holderPosition?: number;
+    };
+}
+/**
+ * Endpoint definition for document nodes.
+ * @public
+ */
+interface DiagramEndpoint {
+    id: string;
+    label: string;
+    face?: DeviceView | 'internal';
+    group?: string;
+    role?: 'network' | 'power' | 'fiber' | 'tube' | 'splice' | 'coupler' | 'splitter' | 'cable' | 'generic';
+    medium?: 'ethernet' | 'fiber' | 'power' | 'tube' | 'generic';
+    type?: PortType;
+    cableType?: PortCableType;
+    connector?: string;
+    compatibility?: string[];
+    layout?: PortPosition;
+}
+/**
+ * Render-focused node data for the document model.
+ * @public
+ */
+interface DiagramNodeRender {
+    status?: DeviceStatus | string;
+    view?: DeviceView;
+    face?: DeviceView;
+    width?: Width | number;
+    widthPx?: number;
+    height?: number;
+    header?: string;
+    color?: string;
+    colorMode?: 'light' | 'dark' | 'system';
+    rackWidthPx?: number;
+    rackFaceGapPx?: number;
+    images?: DeviceImageOptions;
+    dimensions?: Record<string, number | undefined>;
+    showUMarkers?: boolean;
+    customHeaderText?: string;
+    powerSide?: PowerSide;
+    rotation?: number;
+}
+/**
+ * External reference attached to a document node.
+ * @public
+ */
+interface DiagramExternalRef {
+    source: 'netbox' | 'inventory' | string;
+    id: string | number;
+    type?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Document node.
+ * @public
+ */
+interface DiagramNode {
+    id: string;
+    kind: DiagramNodeKind;
+    subtype?: string;
+    label: string;
+    placement: DiagramNodePlacement;
+    endpoints?: DiagramEndpoint[];
+    render?: DiagramNodeRender;
+    config?: Record<string, unknown>;
+    externalRefs?: DiagramExternalRef[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Endpoint reference used by document edges.
+ * @public
+ */
+interface DiagramEdgeEndpoint {
+    nodeId: string;
+    endpointId?: string | null;
+}
+/**
+ * Document edge.
+ * @public
+ */
+interface DiagramEdge {
+    id: string;
+    source: DiagramEdgeEndpoint;
+    target: DiagramEdgeEndpoint;
+    type?: NetworkEdgeType;
+    hidden?: boolean;
+    data?: NetworkEdgeData;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Non-topology UI state stored alongside a document.
+ * @public
+ */
+interface DiagramUiState {
+    nodeState?: Record<string, {
+        view?: DeviceView;
+        face?: DeviceView;
+        handleSideMap?: Record<string, DeviceView>;
+    }>;
+    metadata?: Record<string, unknown>;
+}
 /**
  * Rack device types
  * @public
@@ -759,13 +905,13 @@ interface RackDevice extends DeviceImageOptions {
     mountMode?: RackMountMode;
     /** Device role in network */
     role?: string;
-    /** Flat port input normalized by the renderer */
+    /** Recommended simple port input. Use `portGroups` / `rearPortGroups` for explicit grouped control. */
     ports?: DevicePort[];
     /** Current status of the device */
     status?: DeviceStatus | string;
-    /** Lower-level grouped front port input */
+    /** Advanced grouped front port input */
     portGroups?: PortBlock[];
-    /** Lower-level grouped rear port input */
+    /** Advanced grouped rear port input */
     rearPortGroups?: PortBlock[];
     /** Power port side for rear view */
     powerSide?: PowerSide;
@@ -973,6 +1119,12 @@ interface NetworkDiagramStoreApi {
  * @public
  */
 interface NetworkDiagramProps {
+    /** Controlled document model. When provided, it takes precedence over nodes/edges props. */
+    document?: DiagramDocument;
+    /** Initial document for uncontrolled document mode. */
+    initialDocument?: DiagramDocument;
+    /** Callback when the document changes in document mode. */
+    onDocumentChange?: (document: DiagramDocument) => void;
     /** Controlled nodes array */
     nodes?: NetworkNode[];
     /** Controlled edges array */
@@ -1051,30 +1203,6 @@ interface NetworkDiagramProps {
     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 {
@@ -1194,12 +1322,9 @@ declare const PowerEdge: React$1.FC<EdgeProps>;
  *     label: 'Web Server',
  *     deviceType: 'server',
  *     uPosition: 1,
- *     ports: [{
- *       name: 'Network Ports',
- *       ports: [
- *         { label: 'eth0', connected: true, type: 'ethernet' }
- *       ]
- *     }]
+ *     ports: [
+ *       { id: 'eth0', label: 'eth0', group: 'Network Ports', connected: true, type: 'ethernet' }
+ *     ]
  *   }
  * }
  * ```
@@ -1976,6 +2101,30 @@ declare function hasFrontPorts(data: PortFaceData | undefined): boolean;
 declare function hasRearPorts(data: PortFaceData | undefined): boolean;
 declare function getDefaultDeviceView(data: PortFaceData | undefined): DeviceView;
 
+interface NetworkGraphSnapshot {
+    nodes: NetworkNode[];
+    edges: NetworkEdge[];
+}
+declare function networkGraphToDiagramDocument(snapshot: NetworkGraphSnapshot, previousDocument?: DiagramDocument): DiagramDocument;
+declare function diagramDocumentToNetworkGraph(document: DiagramDocument): NetworkGraphSnapshot;
+
+type EndpointConnectionKind = 'power' | 'network' | 'unknown';
+interface EndpointMetadata {
+    normalizedHandle: string;
+    face?: DeviceView;
+    kind: EndpointConnectionKind;
+    compatibility: string[];
+}
+declare function resolveEndpointCompatibilityKeys(input: {
+    compatibility?: string[];
+    kind?: EndpointConnectionKind;
+    type?: string;
+    cableType?: string;
+    connectorType?: string;
+    handleId?: string;
+}): string[];
+declare function getEndpointMetadata(node?: NetworkNode, handle?: string | null): EndpointMetadata;
+
 /**
  * Power connector utilities for consistent styling across devices and PDUs
  */
@@ -2307,6 +2456,10 @@ interface TemplateParseResult {
  *
  * **Port position semantics**: Positions use `xPercent` / `yPercent` (0-100)
  * to express where the port CENTER should be relative to the device face.
+ * Raw imports may also use semantic edge strings like `top-left` or
+ * `right-middle`; those are normalized into side/offset placements during
+ * import. `xPercent` / `yPercent` remain the manual override path for
+ * detailed templates.
  * The renderer (`DeviceNode`) converts these to pixel coordinates and clamps
  * them so the port stays fully inside the device bounds.  Clamp bounds are
  * computed from the **actual** rendered port dimensions (which vary by port
@@ -2328,7 +2481,7 @@ interface RawTemplatePort {
     type?: string;
     connectorType?: string;
     connector_type?: string;
-    position?: {
+    position?: string | {
         side?: string;
         offsetPercent?: number;
         offset_percent?: number;
@@ -2447,4 +2600,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 DeviceTemplateV2, DiagramErrorBoundary, type DiagramErrorBoundaryProps, FIBER_COLORS_12, type FiberCable, 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 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 PortType, PowerEdge, RACK_HEADER_HEIGHT, RACK_WIDTH_PX, type RackConfig, type RackDevice, 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, 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, fiberSolidOrStriped, findNearestRack, findNextAvailableHolderPosition, findNextAvailableUPosition, generateLayout, getConnectorConfig, getCouplerDimensions, getDefaultDeviceView, getDeviceConnectorType, 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, parseNetboxTemplate, removeDeviceFromRack, removeSpliceFromTray, replaceEdge, snapToCouplerPosition, snapToSplicePosition, snapToUPosition, updateDeviceUPosition$1 as updateDeviceUPosition, updateDeviceUPosition as updateDeviceUPositionInSchema, updateSpliceHolderPosition, useEdges as useDiagramEdges, useNodes as useDiagramNodes, useNetworkDiagram, validateAndSnapDevice, validateRackDevicePlacements, validateRenderFidelity, validateSplicePlacements };
+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 };