@mp70/react-networks 0.6.0 → 0.7.1

package/dist/document-adapter-Jn_0jy4m.d.mts

@@ -0,0 +1,1449 @@
+import { Connection, Node, NodeTypes, EdgeTypes, Edge, ConnectionMode, ReactFlowInstance, Viewport, FitViewOptions } from 'reactflow';
+
+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;
+}
+
+/**
+ * Rack device width configuration
+ * @public
+ */
+
+declare enum Width {
+    /** Full width device (19" rack width) */
+    FULL = "full",
+    /** Half width device (9.5" rack width) */
+    HALF = "half"
+}
+/**
+ * Port configuration for network devices
+ * @public
+ */
+/**
+ * Port type enumeration
+ * @public
+ */
+type PortType = "ethernet" | "rj45" | "fiber" | "console" | "mgmt" | "usb" | "power_ac" | "power_c13" | "power_c19";
+/**
+ * Cable types used for connected network ports.
+ * @public
+ */
+type PortCableType = "smf" | "cat6" | "om3" | "om4" | "om5" | "cat5e" | "cat6a" | "cat7" | "fiber" | "ethernet";
+/**
+ * Device image fit options.
+ *
+ * Values mirror object-fit terms for API ergonomics and are mapped to valid
+ * background-size values by renderers where needed.
+ *
+ * @public
+ */
+type DeviceImageFit = "cover" | "contain" | "contain-height" | "fill" | "none" | "scale-down";
+/**
+ * Device image repeat options.
+ * @public
+ */
+type DeviceImageRepeat = "no-repeat" | "repeat" | "repeat-x" | "repeat-y";
+/**
+ * Shared image configuration for rack-mounted devices and device nodes.
+ * @public
+ */
+interface DeviceImageOptions {
+    /** Optional front image URL for device background (PNG, SVG, JPEG, etc.) */
+    frontImageUrl?: string;
+    /** Optional rear image URL for device background (PNG, SVG, JPEG, etc.) */
+    rearImageUrl?: string;
+    /** Optional attribution URL for front image (e.g. source/license link) */
+    frontImageAttribution?: string;
+    /** Optional attribution URL for rear image (e.g. source/license link) */
+    rearImageAttribution?: string;
+    /** Optional background sizing for device images */
+    imageFit?: DeviceImageFit;
+    /** Optional background position for device images */
+    imagePosition?: string;
+    /** Optional background repeat for device images */
+    imageRepeat?: DeviceImageRepeat;
+    /** When true, stretch device image to fill the device bounds (overrides imageFit) */
+    stretchToFit?: boolean;
+}
+/**
+ * Explicit handle placement for a device/PDU port.
+ * @public
+ */
+interface PortPosition {
+    /** Handle side on the node */
+    side?: "top" | "right" | "bottom" | "left";
+    /** Side offset as percentage (0-100) */
+    offsetPercent?: number;
+    /** Side offset in pixels */
+    offsetPx?: number;
+    /** Absolute X position as percentage (0-100) */
+    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.
+ * 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 {
+    /** Stable handle identifier override (defaults to `group + label`, or `label` for power) */
+    id?: string;
+    /** Display label for the port */
+    label: string;
+    /** Front/rear device face. `back` is accepted as an alias for `rear`. */
+    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 */
+    type?: PortType;
+    /** Cable type for connection validation */
+    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;
+    /**
+     * Optional placement hint.
+     * Use `side` with `offsetPercent`/`offsetPx` for edge-anchored placement,
+     * or `xPercent`/`yPercent` for exact coordinates.
+     */
+    position?: PortPosition;
+}
+interface Port {
+    /** Stable handle identifier override (defaults to `label`) */
+    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 */
+    type?: PortType;
+    /** Cable type for connection validation */
+    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;
+}
+/**
+ * Group of related ports on a device
+ * @public
+ */
+interface PortBlock {
+    /** Name of the port group */
+    name: string;
+    /** Array of ports in this group */
+    ports: Port[];
+}
+/**
+ * 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" | "multi-tube-cable" | "coupler" | "closure" | "fibre-split" | "fibre-flow-cable" | "fibre-flow-closure";
+/**
+ * Device status states
+ * @public
+ */
+type DeviceStatus = "active" | "inactive" | "maintenance";
+/**
+ * Device face orientations
+ * @public
+ */
+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
+ */
+type RackLayoutMode = "single-face" | "split-face";
+/**
+ * Rack mounting behavior for a device.
+ * @public
+ */
+type RackMountMode = "front" | "rear" | "both";
+/**
+ * Power port side configuration
+ * @public
+ */
+type PowerSide = "left" | "right";
+/**
+ * U numbering direction for racks
+ * @public
+ */
+type UNumberingDirection = "bottom-up" | "top-down";
+/**
+ * Shared node data fields available across node types.
+ * Specific node kinds can narrow these fields via `NetworkNodeDataByType`.
+ * @public
+ */
+interface NetworkNodeDataBase extends DeviceImageOptions {
+    /** Display label for the node */
+    label: string;
+    /** Current status of the node/device */
+    status?: DeviceStatus | string;
+    /** 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 */
+    netboxId?: number | string;
+    /** NetBox object type */
+    netboxType?: "device" | "rack" | "interface" | "cable" | string;
+    /** Inventory integration ID */
+    inventoryId?: number | string;
+    /** Inventory object type */
+    inventoryType?: "device" | "rack" | "interface" | "cable" | string;
+    /** Rack height in U units */
+    uHeight?: number;
+    /** Device position within rack in U units */
+    uPosition?: number;
+    /** Whether this node is currently mounted inside a rack container */
+    isRackMounted?: boolean;
+    /** 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 */
+    rackFaceGapPx?: number;
+    /** Device mount behavior within a rack */
+    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 face */
+    powerSide?: PowerSide;
+    /** Vertical PDU height in centimeters */
+    heightCm?: number;
+    /** Number of AC power ports */
+    powerPorts?: number;
+    /** Optional explicit PDU connector sequence */
+    portTypes?: Array<"C13" | "C19">;
+    /** Optional grouped PDU ports (supports custom positions/types) */
+    pduPortGroups?: PortBlock[];
+    /** Vertical PDU width in pixels */
+    widthPx?: number;
+    /** Optional management unit position for vertical PDUs */
+    mgmt_unit?: "top" | "middle" | "bottom";
+    /** U numbering direction for rack nodes */
+    uNumberingDirection?: UNumberingDirection;
+    /** Custom header text for rack nodes */
+    customHeaderText?: string;
+    /** Rack UI marker visibility */
+    showUMarkers?: boolean;
+    /** Holder position within tray (1-12) for splice nodes */
+    holderPosition?: number;
+    /** Loss value in dB for splice nodes */
+    lossDb?: number;
+    /** Splice mode */
+    mode?: "single" | "ribbon";
+    /** Legacy ribbon flag */
+    ribbon?: boolean;
+    /** Ribbon fiber IDs */
+    ribbonFiberIds?: number[];
+    /** Connector type for coupler nodes */
+    connector?: "SC" | "LC";
+    /** Number of fibers for coupler nodes (1, 2, or 4) */
+    couplerFiberCount?: 1 | 2 | 4;
+    /** Optional port labels for left side of coupler */
+    portLabelsLeft?: string[];
+    /** Optional port labels for right side of coupler */
+    portLabelsRight?: string[];
+    /** Slot position for couplers inside panels (1-based, vertical slots aligned to right edge) */
+    slotPosition?: number;
+    /** Width override for panel-like container nodes */
+    panelWidth?: number;
+    /** Height override for panel-like container nodes */
+    panelHeight?: number;
+    /** Width override for closure nodes */
+    closureWidth?: number;
+    /** Height override for closure nodes */
+    closureHeight?: 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;
+    /** Number of trays for closure nodes */
+    trayCount?: 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;
+    /** Tube index (1-based) */
+    tubeIndex?: number;
+    /** Tube count for multi-tube cables */
+    tubeCount?: number;
+    /** Tube start index for multi-tube cables */
+    tubeStartIndex?: number;
+    /** Number of fibers per tube */
+    fibersPerTube?: number;
+    /** Total fiber count for cables */
+    fiberCount?: number;
+    /** Cable identifier */
+    cableId?: string;
+    /** Primary node color override */
+    color?: string;
+    /** Rotation in degrees for rotatable nodes */
+    rotation?: number;
+    /** Tube handle orientation */
+    startOn?: "left-center" | "left" | "right";
+    /** Rack metadata for integrations */
+    facilityId?: string | number | null;
+    /** Rack serial metadata */
+    serial?: string | null;
+    /** Asset tag metadata */
+    assetTag?: string | null;
+    /** Site metadata */
+    site?: string;
+    /** Tenant metadata */
+    tenant?: string;
+    /** Primary IPv4 metadata */
+    primaryIp4?: string;
+    /** Primary IPv6 metadata */
+    primaryIp6?: string;
+    /** Rack name metadata */
+    rack?: string | number | null;
+    /** Optional arrays used by inventory/netbox transforms */
+    racks?: unknown[];
+    devices?: unknown[];
+    cables?: unknown[];
+    /** UI color mode metadata */
+    colorMode?: "light" | "dark" | "system";
+    /** Generic dimensions used by some helpers */
+    height?: number;
+    headerHeight?: number;
+    /** Optional precomputed map for handle-to-face resolution */
+    handleSideMap?: Record<string, DeviceFace>;
+    /** Additional extension metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Rack node data.
+ * @public
+ */
+interface RackNodeData extends NetworkNodeDataBase {
+    ports?: number;
+}
+/**
+ * Device-like node data (servers/switches/routers/generic device).
+ * @public
+ */
+interface DeviceNodeData extends NetworkNodeDataBase {
+    ports?: DevicePort[] | PortBlock[] | number;
+}
+/**
+ * Fibre flow cable node data.
+ * @public
+ */
+interface FibreFlowCableNodeData extends NetworkNodeDataBase {
+    cable: FibreFlowCable;
+    side: "left" | "right";
+    rowHeight: number;
+    columnWidth: number;
+    showTubeLabels: boolean;
+    showFiberNumbers: boolean;
+    layout: unknown;
+    colorMode?: "dark" | "light";
+}
+/**
+ * Fibre flow closure node data.
+ * @public
+ */
+interface FibreFlowClosureNodeData extends NetworkNodeDataBase {
+    width?: number;
+    height?: number;
+    headerHeight?: number;
+    colorMode?: "dark" | "light";
+}
+/**
+ * Mapping from node type to corresponding data type.
+ * @public
+ */
+interface NetworkNodeDataByType {
+    rack: RackNodeData;
+    switch: DeviceNodeData;
+    router: DeviceNodeData;
+    server: DeviceNodeData;
+    fiber: NetworkNodeDataBase;
+    "patch-panel": NetworkNodeDataBase;
+    device: DeviceNodeData;
+    "vertical-pdu": NetworkNodeDataBase;
+    splice: NetworkNodeDataBase;
+    "splice-tray": NetworkNodeDataBase;
+    tube: NetworkNodeDataBase;
+    cable: NetworkNodeDataBase;
+    "multi-tube-cable": NetworkNodeDataBase;
+    coupler: NetworkNodeDataBase;
+    closure: NetworkNodeDataBase;
+    "fibre-split": NetworkNodeDataBase;
+    "fibre-flow-cable": FibreFlowCableNodeData;
+    "fibre-flow-closure": FibreFlowClosureNodeData;
+}
+/**
+ * Union of all node data variants.
+ * @public
+ */
+type NetworkNodeData = NetworkNodeDataByType[NetworkNodeType];
+/**
+ * Network node structure with data discriminated by `type`.
+ * @public
+ */
+type NetworkNode<TType extends NetworkNodeType = NetworkNodeType, TExtra = unknown> = TType extends NetworkNodeType ? Node<NetworkNodeDataByType[TType] & TExtra, TType> & {
+    /** Type of network node */
+    type: TType;
+    /** Node data and configuration */
+    data: NetworkNodeDataByType[TType] & TExtra;
+} : never;
+/**
+ * Network edge types
+ * @public
+ */
+type NetworkEdgeType = "fiber" | "ethernet" | "power" | "smoothstep" | "step" | "thick-cable" | "fibre-flow" | "fibre-flow-link";
+/**
+ * Edge data payload.
+ * @public
+ */
+interface NetworkEdgeData {
+    /** Connection bandwidth */
+    bandwidth?: string;
+    /** Cable length */
+    length?: number;
+    /** Edge color for styling */
+    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;
+    /** Legacy striped edge flag */
+    striped?: boolean;
+    /** Cable type metadata used by demos/helpers */
+    cableType?: PortCableType;
+    /** NetBox integration metadata */
+    netboxId?: number | string;
+    netboxType?: "device" | "rack" | "interface" | "cable" | string;
+    /** Inventory integration metadata */
+    inventoryId?: number | string;
+    inventoryType?: "device" | "rack" | "interface" | "cable" | string;
+    /** Status metadata */
+    status?: string;
+    /** Endpoint metadata */
+    terminationA?: string;
+    terminationB?: string;
+    /** Optional display label for the edge */
+    label?: string;
+    /** Optional opacity for styling (0–1) */
+    opacity?: number;
+    /** Optional power edge stroke width override */
+    powerStrokeWidth?: number;
+    /** Optional power edge stroke dasharray override */
+    powerStrokeDasharray?: string;
+    /** Optional power edge opacity override (0–1) */
+    powerOpacity?: number;
+    /** Additional extension metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Network edge data structure
+ * @public
+ */
+type NetworkEdge<TData extends NetworkEdgeData = NetworkEdgeData> = {
+    /** Unique identifier for the edge */
+    id: string;
+    /** Source node ID */
+    source: string;
+    /** Target node ID */
+    target: string;
+    /** Source handle/port ID */
+    sourceHandle?: string;
+    /** Target handle/port ID */
+    targetHandle?: string;
+    /** Type of network connection */
+    type?: NetworkEdgeType;
+    /** Whether the edge should be hidden from rendering */
+    hidden?: boolean;
+    /** Edge data and configuration */
+    data?: TData;
+};
+/**
+ * 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 {
+    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?: DeviceFace | "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;
+    face?: DeviceFace;
+    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, {
+        face?: DeviceFace;
+        handleSideMap?: Record<string, DeviceFace>;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Rack device types
+ * @public
+ */
+type RackDeviceType = "server" | "switch" | "router" | "patch-panel" | "ups";
+/**
+ * Rack configuration structure
+ * @public
+ */
+interface RackConfig {
+    /** Unique rack identifier */
+    id: string;
+    /** Rack display name */
+    name: string;
+    /** Rack position coordinates */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Rack height in U units */
+    units: number;
+    /** U numbering direction (default: 'bottom-up') */
+    uNumberingDirection?: UNumberingDirection;
+    /** Custom header text for rack */
+    customHeaderText?: string;
+    /** Rack rendering layout mode */
+    rackLayout?: RackLayoutMode;
+    /** Gap in pixels between front and rear faces in split-face mode */
+    rackFaceGapPx?: number;
+    /** 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
+ * @public
+ */
+interface RackDevice extends DeviceImageOptions {
+    /** Unique device identifier */
+    id: string;
+    /** Device display name */
+    name: string;
+    /** Starting U position in rack */
+    unit: number;
+    /** Device height in U units */
+    height: number;
+    /** Device type */
+    type: RackDeviceType;
+    /** Device width configuration */
+    width?: Width;
+    /** Device mount behavior within a rack */
+    mountMode?: RackMountMode;
+    /** Device role in network */
+    role?: string;
+    /** 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[];
+    /** Grouped rear port blocks (rack JSON alias for `rearPortGroups`) */
+    rearPorts?: PortBlock[];
+    /** Power port side for rear face */
+    powerSide?: PowerSide;
+    /** Connected device IDs */
+    connections?: string[];
+}
+/**
+ * Fiber cable types
+ * @public
+ */
+type FiberCableType = "single-mode" | "multi-mode";
+/**
+ * Fiber cable configuration
+ * @public
+ */
+interface FiberCable {
+    /** Unique cable identifier */
+    id: string;
+    /** Cable display name */
+    name: string;
+    /** Fiber cable type */
+    type: FiberCableType;
+    /** Cable length */
+    length: number;
+    /** Cable color for visualization */
+    color: string;
+    /** Connection endpoints */
+    connections: {
+        /** Source connection point */
+        from: string;
+        /** Target connection point */
+        to: string;
+    };
+}
+/**
+ * Splice configuration structure
+ * @public
+ */
+interface SpliceConfig {
+    /** Unique splice identifier */
+    id: string;
+    /** Splice display name */
+    name: string;
+    /** Holder position within tray (1-12) */
+    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
+ * @public
+ */
+interface SpliceTrayConfig {
+    /** Unique tray identifier */
+    id: string;
+    /** Tray display name */
+    name: string;
+    /** Tray position coordinates */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Splices in this tray */
+    splices: SpliceConfig[];
+}
+/**
+ * Fine-grained interaction controls for network diagrams.
+ * @public
+ */
+interface NetworkDiagramInteractionOptions {
+    /** Enable node dragging. */
+    nodesDraggable?: boolean;
+    /** Enable creating connections from node handles. */
+    nodesConnectable?: boolean;
+    /** Enable selecting nodes/edges. */
+    elementsSelectable?: boolean;
+    /** Enable keyboard/mouse focus on edges. */
+    edgesFocusable?: boolean;
+    /** Enable reconnecting existing edges. */
+    edgesReconnectable?: boolean;
+    /** Enable click-to-connect behavior on handles. */
+    connectOnClick?: boolean;
+    /** Enable panning by dragging the canvas. */
+    panOnDrag?: boolean;
+    /** Enable panning by scrolling. */
+    panOnScroll?: boolean;
+    /** Enable zoom via mouse wheel/trackpad scroll. */
+    zoomOnScroll?: boolean;
+    /** Enable pinch-zoom gestures. */
+    zoomOnPinch?: boolean;
+    /** Enable zoom on double click. */
+    zoomOnDoubleClick?: boolean;
+    /** Enable deleting selected edges with keyboard keys. */
+    allowKeyboardDelete?: boolean;
+    /** Show or hide the built-in React Flow controls widget. */
+    showControls?: boolean;
+    /** Show or hide the minimap. */
+    showMiniMap?: boolean;
+    /** Show or hide the interactive lock/unlock button in controls. */
+    showInteractiveControl?: boolean;
+}
+/**
+ * Selection action panel options rendered above selected racks/devices.
+ * @public
+ */
+interface NetworkDiagramActionPanelOptions {
+    /** Enable or disable the floating action panel entirely. Defaults to true. */
+    enabled?: boolean;
+    /** Show or hide the front/rear toggle button. Defaults to true. */
+    showRearToggle?: boolean;
+    /** Show or hide the De-rack button for rack-mounted devices. Defaults to true. */
+    showDeRack?: boolean;
+}
+/**
+ * Serializable flow snapshot payload for save/restore helpers.
+ * @public
+ */
+interface NetworkDiagramFlowObject {
+    /** Snapshot nodes */
+    nodes: NetworkNode[];
+    /** Snapshot edges */
+    edges: NetworkEdge[];
+    /** Optional viewport state */
+    viewport?: Viewport;
+}
+/**
+ * Options for exported diagram images.
+ * @public
+ */
+interface NetworkDiagramToImageOptions {
+    /** Export width in px (clamped to 1-8192). */
+    width?: number;
+    /** Export height in px (clamped to 1-8192). */
+    height?: number;
+    backgroundColor?: string;
+    /** Export padding in px (clamped to 0-2048). */
+    padding?: number;
+    /** Device pixel ratio multiplier (clamped to 0.1-4). */
+    pixelRatio?: number;
+    /** JPEG/WebP quality (clamped to 0-1 when used). */
+    quality?: number;
+    filter?: (domNode: HTMLElement) => boolean;
+}
+/**
+ * Fit-view options that support targeting node IDs directly.
+ * @public
+ */
+interface NetworkDiagramFitViewOptions extends Omit<FitViewOptions, "nodes"> {
+    /** Optional node IDs to fit */
+    nodes?: string[];
+}
+/**
+ * Exposed methods for save/restore and export integrations.
+ * @public
+ */
+interface NetworkDiagramFlowMethods {
+    toObject: () => NetworkDiagramFlowObject;
+    setViewport: (viewport: Viewport) => void;
+    setNodes: (nodes: NetworkNode[]) => void;
+    setEdges: (edges: NetworkEdge[]) => void;
+    toImage: (options?: NetworkDiagramToImageOptions) => Promise<string>;
+    getNodes: () => NetworkNode[];
+    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: () => NetworkDiagramStoreState;
+    setState: (partial: Partial<NetworkDiagramStoreState>) => void;
+    subscribe: (listener: (state: NetworkDiagramStoreState) => void) => () => void;
+    selectEdgeZIndex: (edge: NetworkEdge) => number;
+    validateConnection: (params: NetworkDiagramValidateConnectionParams) => NetworkDiagramValidationResult;
+    selectNodeById: (id: string) => NetworkNode | undefined;
+    selectConnectedEdges: (nodeId: string) => NetworkEdge[];
+}
+/**
+ * Network diagram component props
+ * @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 */
+    edges?: NetworkEdge[];
+    /** Callback when nodes change (controlled mode) */
+    onNodesChange?: (nodes: NetworkNode[]) => void;
+    /** Callback when edges change (controlled mode) */
+    onEdgesChange?: (edges: NetworkEdge[]) => void;
+    /** Initial nodes for uncontrolled mode */
+    initialNodes?: NetworkNode[];
+    /** Initial edges for uncontrolled mode */
+    initialEdges?: NetworkEdge[];
+    /** Headless store injection */
+    store?: NetworkDiagramStoreApi;
+    /** Enable debug mode */
+    debug?: boolean;
+    /** Callback when a node is clicked or selection changes (null when deselected) */
+    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 a device face changes */
+    onFaceChange?: (nodeId: string, face: DeviceFace) => void;
+    /** Callback when rack face changes */
+    onRackFaceChange?: (rackId: string, face: DeviceFace) => void;
+    /** CSS class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+    /** If true, vertically align rack bottoms to the same baseline */
+    alignRacksToBottom?: boolean;
+    /** Allow rack-mounted devices to move between racks/ungroup on drag and drop. Defaults to true. */
+    reAssignable?: boolean;
+    /** Color mode for the diagram */
+    colorMode?: "light" | "dark" | "system";
+    /** Callback when React Flow instance is initialized */
+    onInit?: (instance: ReactFlowInstance) => void;
+    /** Callback to get React Flow methods for save/restore */
+    onFlowMethods?: (methods: NetworkDiagramFlowMethods) => void;
+    /** Show download button */
+    showDownloadButton?: boolean;
+    /** Download button position */
+    downloadButtonPosition?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+    /** Custom download button text */
+    downloadButtonText?: string;
+    /** Download button styling options */
+    downloadButtonStyle?: React.CSSProperties;
+    /** Use smoothstep edges for tube connections (both tube-to-cable and cable-to-tube). Default is fiber. */
+    useSmoothstepEdgesForTubes?: boolean;
+    /** Force read-only behavior for the diagram (no drag/connect/delete/reconnect/pan/zoom edits). */
+    readOnly?: boolean;
+    /** Centralized interaction options for consistent edit/lock behavior. */
+    interaction?: NetworkDiagramInteractionOptions;
+    /** Configuration for the floating action panel shown on selected rack/device nodes. */
+    actionPanel?: NetworkDiagramActionPanelOptions;
+    /** Optional fitView options passed to React Flow */
+    fitViewOptions?: FitViewOptions;
+    /**
+     * Minimum zoom passed to React Flow. Defaults to 0.1 so the always-on
+     * fitView can actually fit tall scenes (React Flow's own 0.5 default clamps
+     * the fit and crops full-height racks, which viewport culling then never
+     * mounts).
+     */
+    minZoom?: number;
+    /** Maximum zoom passed to React Flow. Defaults to 4. */
+    maxZoom?: number;
+    /**
+     * Let React Flow render only viewport-visible nodes and edges.
+     * Defaults to `false`. Enable for very large diagrams, but note that with a
+     * tight `minZoom` a fit-to-view can cull off-screen nodes so they never mount.
+     */
+    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;
+    /**
+     * Pointer distance (px) within which a drag snaps onto a handle, forwarded to
+     * React Flow's `connectionRadius`. Larger values make small port handles easier
+     * to target; smaller values reduce mis-targeting on densely packed devices.
+     * When omitted, React Flow's default is used.
+     */
+    connectionRadius?: number;
+    /**
+     * Fired when a connection attempt is rejected by the diagram's validation
+     * (incompatible endpoints, an occupied non-replaceable handle, a disallowed
+     * fiber pairing, etc.). Lets host apps surface feedback instead of failing
+     * silently. Not called for the continuous hover validation during a drag —
+     * only when an actual connect or reconnect attempt is rejected.
+     */
+    onConnectRejected?: (payload: NetworkConnectionRejection) => void;
+}
+/** Payload describing why a connection attempt was rejected. */
+interface NetworkConnectionRejection {
+    /** The connection the user attempted to make. */
+    connection: Connection;
+    /** Human-readable reason the connection was rejected. */
+    reason: string;
+    /** Whether the rejection happened while creating a new edge or reconnecting an existing one. */
+    phase: "connect" | "reconnect";
+}
+
+/**
+ * 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 the directional suffix and the split-face alias, in the order
+ * the renderer composes them: `<base>[--rear|--front][-source|-target]`.
+ * (Previously only `--rear` was stripped; `--front` ghost aliases now
+ * normalize too.)
+ */
+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;
+/**
+ * Options for {@link applyDirectionalPortHandleId}.
+ */
+interface ApplyDirectionalPortHandleIdOptions {
+    /**
+     * The port's `type` (e.g. `rj45`, `power_ac`). When provided, power-ness is
+     * decided from it via {@link isPowerPortType} — the same rule the renderer
+     * uses to decide whether a port mounts directional handles at all. Always
+     * pass this when the port is available.
+     */
+    portType?: string;
+}
+/**
+ * Apply a directional (`source`/`target`) suffix to a rendered handle id — the
+ * inverse of {@link normalizeDirectionalHandleId}. Any existing directional
+ * suffix is replaced first, and passing no direction is a no-op.
+ * Example: `Rear Ports-1` + `target` -\> `Rear Ports-1-target`.
+ *
+ * Power endpoints are matched without a direction, so power handles are
+ * returned unchanged. Whether a handle is a power handle is decided from
+ * `options.portType` when given (exact — the renderer's rule). Without it the
+ * decision falls back to {@link looksLikePowerHandleId}, a string heuristic
+ * that cannot recognize power ports whose ids lack `power`/`pwr` (e.g. a port
+ * labeled `PSU-A`) and misclassifies non-power ports whose group name contains
+ * the word (e.g. `Power Room Uplinks-1`). Pass `portType` whenever you have
+ * the port.
+ */
+declare function applyDirectionalPortHandleId(handleId: string, direction?: "source" | "target" | null, options?: ApplyDirectionalPortHandleIdOptions): string;
+/**
+ * The structural shape of a handle id's base (suffixes already stripped).
+ *
+ * - `outlet` — vertical-PDU outlets: a bare number (`"4"`).
+ * - `fiber` — `fiber-<n>` (tube/cable nodes) or `fiber-<tube>-<n>`
+ *   (FibreFlowMap rows).
+ * - `tube` — `tube-<n>` (tube and multi-tube-cable nodes).
+ * - `splice-side` — bare `left` / `right` (splice nodes).
+ * - `side-port` — `left-<n>` / `right-<n>` (coupler ports).
+ * - `split-io` — `input-<n>` / `output-<n>` (fibre-split nodes).
+ * - `cable-button` — the literal `cable-button` connector on cable nodes.
+ * - `port` — everything else: device-family ports built by
+ *   {@link buildPortHandleId} (`<group>-<label>`, a bare power label, or an
+ *   explicit `port.id`). The base is not split further because group names
+ *   and labels may themselves contain `-`.
+ * @public
+ */
+type HandleShape = {
+    kind: "outlet";
+    outlet: number;
+} | {
+    kind: "fiber";
+    fiber: number;
+    tube?: number;
+} | {
+    kind: "tube";
+    tube: number;
+} | {
+    kind: "splice-side";
+    side: "left" | "right";
+} | {
+    kind: "side-port";
+    side: "left" | "right";
+    index: number;
+} | {
+    kind: "split-io";
+    io: "input" | "output";
+    index: number;
+} | {
+    kind: "cable-button";
+} | {
+    kind: "port";
+};
+/**
+ * A structurally parsed handle id.
+ * @public
+ */
+interface ParsedHandleId {
+    /** The id exactly as given. */
+    raw: string;
+    /** `raw` with the directional suffix and face alias stripped. */
+    base: string;
+    /** Directional suffix, when present (`X-source` / `X-target`). */
+    direction?: "source" | "target";
+    /**
+     * Split-face alias, when present (`X--rear` / `X--front`) — added by the
+     * renderer when both faces of a device are shown and a handle id would
+     * otherwise collide with its opposite face.
+     */
+    faceAlias?: "front" | "rear";
+    /** Structural classification of {@link ParsedHandleId.base}. */
+    shape: HandleShape;
+}
+/**
+ * Parse a rendered/stored handle id into its structural parts: base, optional
+ * directional suffix, optional split-face alias, and the {@link HandleShape}
+ * of the base. Total — never throws; unrecognized bases classify as `port`.
+ * @public
+ */
+declare function parseHandleId(handleId: string | null | undefined): ParsedHandleId;
+/**
+ * Build a fiber handle id: `fiber-<n>`, or `fiber-<tube>-<n>` when a tube
+ * index is given (the FibreFlowMap row form).
+ * @public
+ */
+declare function buildFiberHandleId(fiber: number, tube?: number): string;
+/**
+ * Build a tube handle id: `tube-<n>`.
+ * @public
+ */
+declare function buildTubeHandleId(tube: number): string;
+/**
+ * Build a splice handle id: the bare `left` / `right` sides of a splice node.
+ * @public
+ */
+declare function buildSpliceHandleId(side: "left" | "right"): string;
+/**
+ * Build a coupler port handle id: `left-<n>` / `right-<n>` (1-based).
+ * @public
+ */
+declare function buildCouplerHandleId(side: "left" | "right", index: number): string;
+/**
+ * Build a fibre-split io handle id: `input-<n>` / `output-<n>`.
+ * @public
+ */
+declare function buildSplitIoHandleId(io: "input" | "output", index: number): string;
+/**
+ * Append a split-face alias to a handle id: `X` + `rear` -\> `X--rear`.
+ * Any existing alias is replaced. The renderer applies this when a hidden or
+ * ghost face would mount a handle whose id collides with the visible face.
+ * @public
+ */
+declare function applyFaceAliasHandleId(handleId: string, face: "front" | "rear"): string;
+/**
+ * Normalize a handle id for tolerant matching by stripping `+` characters.
+ * Port labels like `SFP+-1` historically produced handles that some producers
+ * emitted `+`-stripped (`SFP-1`), so comparisons between independently built
+ * handles must be `+`-insensitive. Apply to BOTH sides of a comparison — this
+ * is a matching normalization, not part of the build grammar:
+ * {@link buildPortHandleId} keeps `+` so built ids always equal rendered ids.
+ * @public
+ */
+declare function sanitizeHandleIdForMatching(handleId: string): string;
+/**
+ * For pass-through nodes with two sides, return the handle id of the opposite
+ * side: splice `left` \<-\> `right`, coupler `left-<n>` \<-\> `right-<n>`.
+ * Returns `undefined` for every other shape. Directional suffixes and face
+ * aliases are stripped (neither occurs on splice/coupler handles in practice).
+ * @public
+ */
+declare function getOppositeSideHandleId(handleId: string): string | undefined;
+
+/** @deprecated Use {@link buildPortHandleId}. */
+declare const buildReactNetworksHandleId: typeof buildPortHandleId;
+/**
+ * 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 **flat** port array input into canonical {@link DevicePort} entries.
+ *
+ * This handles a flat `DevicePort[]` only; grouped `PortBlock[]` input returns
+ * `undefined` (blocks have no `label`). To resolve flat ports from any supported
+ * form — including grouped `PortBlock[]` — use {@link resolveNodeDevicePorts}.
+ * @public
+ */
+declare function normalizeDevicePorts(value: unknown): DevicePort[] | undefined;
+/** @deprecated Use {@link normalizeDevicePorts}. */
+declare const normalizeReactNetworksPorts: typeof normalizeDevicePorts;
+/**
+ * Resolve flat device ports from any supported port input.
+ *
+ * Accepts every form the renderer accepts (`getResolvedPortBlocks`): a node-data
+ * record (`ports` / `portGroups` / `rearPortGroups` / `rearPorts`), a flat
+ * `DevicePort[]`, or a grouped `PortBlock[]`. Grouped `PortBlock[]` carried on
+ * `ports` are treated as front groups (taking precedence over `portGroups`, matching
+ * the renderer); rear groups come from `rearPortGroups`, falling back to `rearPorts`.
+ * @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 the **canonical** handle ids that may exist on a rendered node for a port.
+ *
+ * The returned ids are in canonical form. When a device renders both faces and a
+ * front/rear handle id collides, the renderer disambiguates the hidden face with a
+ * `--rear` / `--front` suffix (see `normalizeHandleId`). This function does not emit
+ * those split-face aliases, so callers reconciling stored/rendered handles should
+ * compare through {@link normalizeHandleId} (which strips the suffix) rather than by
+ * raw string equality. {@link validatePortHandleOnNodeData} does this for you.
+ * @public
+ */
+declare function listPossiblePortHandleIds(portBlockName: string, port: Pick<Port, 'id' | 'label' | 'type'>, options?: ListPossiblePortHandleIdsOptions): string[];
+/**
+ * A rendered/stored handle id resolved back to the port that owns it.
+ * @public
+ */
+interface DescribedPortHandle {
+    /** The port the handle belongs to. */
+    port: DevicePort;
+    /** The port block (group) the port renders under. */
+    blockName: string;
+    /** The device face the block renders on. */
+    face: DeviceFace;
+}
+/**
+ * Resolve a handle id back to the port that owns it — the inverse of
+ * {@link buildPortHandleId} / {@link listPossiblePortHandleIds} over a node's
+ * resolved port blocks. Directional suffixes and split-face aliases are
+ * normalized before comparison (via {@link normalizeHandleId}), so ids taken
+ * straight from edges match. Pass `options.sanitizeHandle` to match under an
+ * additional app-side normalization (e.g.
+ * {@link sanitizeHandleIdForMatching} for `+`-insensitive comparison).
+ * Returns `undefined` when no port on the node renders that handle.
+ * @public
+ */
+declare function describePortHandle(nodeData: Pick<NetworkNodeDataBase, 'ports' | 'portGroups' | 'rearPortGroups'> | undefined, handle: string, options?: {
+    deviceType?: string;
+    sanitizeHandle?: (value: string) => string;
+}): DescribedPortHandle | undefined;
+/**
+ * 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[];
+    edges: NetworkEdge[];
+}
+declare function networkGraphToDiagramDocument(snapshot: NetworkGraphSnapshot, previousDocument?: DiagramDocument): DiagramDocument;
+declare function diagramDocumentToNetworkGraph(document: DiagramDocument): NetworkGraphSnapshot;
+
+export { type NetworkDiagramFlowObject as $, type ApplyDirectionalPortHandleIdOptions as A, type BuildPathLayoutOptions as B, type DiagramEdgeEndpoint as C, type DeviceNodeData as D, type DiagramEndpoint as E, type FibreFlowCableNodeData as F, type DiagramExternalRef as G, type DiagramNode as H, type DiagramNodeKind as I, type DiagramNodePlacement as J, type DiagramNodeRender as K, type DiagramUiState as L, type FiberCable as M, type NetworkDiagramProps as N, type FiberCableType as O, type PortBlock as P, type FibreFlowCableKind as Q, type RackNodeData as R, type SpliceTrayConfig as S, type FibreFlowEndpoint as T, type FibreFlowSplice as U, type HandleShape as V, type ListPossiblePortHandleIdsOptions as W, type NetworkConnectionRejection as X, type NetworkDiagramActionPanelOptions as Y, type NetworkDiagramFitViewOptions as Z, type NetworkDiagramFlowMethods as _, type NetworkNode as a, type NetworkDiagramStoreApi as a0, type NetworkDiagramStoreState as a1, type NetworkDiagramToImageOptions as a2, type NetworkDiagramValidateConnectionParams as a3, type NetworkDiagramValidationResult as a4, type NetworkEdgeType as a5, type NetworkGraphSnapshot as a6, type NetworkNodeData as a7, type NetworkNodeDataByType as a8, type NetworkNodeType as a9, flattenReactNetworksPortGroups as aA, getOppositeSideHandleId as aB, isPowerPortType as aC, listPossiblePortHandleIds as aD, looksLikePowerHandleId as aE, networkGraphToDiagramDocument as aF, normalizeDevicePorts as aG, normalizeDirectionalHandleId as aH, normalizeHandleId as aI, normalizePortPositionInput as aJ, normalizeReactNetworksPorts as aK, parseHandleId as aL, parseSemanticPortPosition as aM, resolveDevicePortBlocksFromFlatPorts as aN, resolveDevicePortFace as aO, resolveDevicePortGroup as aP, resolveNodeDevicePorts as aQ, resolveReactNetworksNodePorts as aR, resolveReactNetworksPortFace as aS, resolveReactNetworksPortGroup as aT, sanitizeHandleIdForMatching as aU, validatePortHandleOnNodeData as aV, type ParsedHandleId as aa, type PathLayoutDirection as ab, type PathLayoutEdgeInput as ac, type PathLayoutStepInput as ad, type Port as ae, type PowerSide as af, type RackDeviceType as ag, type RackLayoutMode as ah, type RackMountMode as ai, type UNumberingDirection as aj, Width as ak, applyDirectionalPortHandleId as al, applyFaceAliasHandleId as am, buildCouplerHandleId as an, buildDevicePortGroupsFromPorts as ao, buildFiberHandleId as ap, buildPathLayoutGraph as aq, buildPortHandleId as ar, buildReactNetworksHandleId as as, buildReactNetworksPortGroupsFromPorts as at, buildSpliceHandleId as au, buildSplitIoHandleId as av, buildTubeHandleId as aw, describePortHandle as ax, diagramDocumentToNetworkGraph as ay, flattenDevicePortsFromGroups as az, type NetworkNodeDataBase as b, type FibreFlowClosureNodeData as c, type NetworkEdgeData as d, type FibreFlowClosure as e, type FibreFlowCircuit as f, type NetworkDiagramInteractionOptions as g, type FibreFlowCable as h, type NetworkEdge as i, type DiagramDocument as j, type RackConfig as k, type RackDevice as l, type SpliceConfig as m, type DevicePort as n, type DeviceFace as o, type PortType as p, type DeviceStatus as q, type DiagramPortHandleRef as r, type DiagramPortClickPayload as s, type PortCableType as t, type PortPosition as u, type DescribedPortHandle as v, type DeviceImageFit as w, type DeviceImageOptions as x, type DeviceImageRepeat as y, type DiagramEdge as z };