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

package/dist/index.d.ts

@@ -65,7 +65,7 @@ interface NetBoxDeviceTransformOptions {
     includeInterfacePorts?: boolean;
     /** Include per-port position metadata when provided */
     includePortPositions?: boolean;
-    /** Optional mapper for full control over interface->port mapping */
+    /** Optional mapper for full control over interface-to-port mapping */
     mapInterfaceToPort?: (args: {
         device: NetBoxDevice;
         iface: NetBoxInterface;
@@ -78,6 +78,7 @@ interface NetBoxDevice {
     device_type: {
         id: number;
         model: string;
+        u_height?: number;
         manufacturer: {
             name: string;
         };
@@ -253,7 +254,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
@@ -296,10 +297,15 @@ interface PortPosition {
     xPercent?: number;
     /** Absolute Y position as percentage (0-100) */
     yPercent?: number;
+    /** Authored port width as a percentage of the rendered image frame */
+    widthPercent?: number;
+    /** Authored port height as a percentage of the rendered image frame */
+    heightPercent?: number;
 }
 /**
- * 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 {
@@ -308,9 +314,11 @@ interface DevicePort {
     /** Display label for the port */
     label: string;
     /** Front/rear device face. `back` is accepted as an alias for `rear`. */
-    face?: DeviceView | 'back';
+    face?: DeviceFace | 'back';
     /** Optional block/group name (for example `Network Ports`, `QSFP28`, `Power Ports`) */
     group?: string;
+    /** Optional source/detected family label used for visual kind inference */
+    sourceTypeLabel?: string;
     /** Whether the port is currently connected */
     connected?: boolean;
     /** Type of port for styling and validation */
@@ -319,6 +327,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;
     /**
@@ -333,6 +343,8 @@ interface Port {
     id?: string;
     /** Display label for the port */
     label: string;
+    /** Optional source/detected family label used for visual kind inference */
+    sourceTypeLabel?: string;
     /** Whether the port is currently connected */
     connected: boolean;
     /** Type of port for styling and validation */
@@ -341,6 +353,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;
 }
@@ -365,10 +379,10 @@ type NetworkNodeType = 'rack' | 'switch' | 'router' | 'server' | 'fiber' | 'patc
  */
 type DeviceStatus = 'active' | 'inactive' | 'maintenance';
 /**
- * Device view orientations
+ * Device face orientations
  * @public
  */
-type DeviceView = 'front' | 'rear';
+type DeviceFace = 'front' | 'rear';
 /**
  * Rack rendering layout modes.
  * @public
@@ -399,11 +413,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,10 +433,10 @@ interface NetworkNodeDataBase extends DeviceImageOptions {
     uHeight?: number;
     /** Device position within rack in U units */
     uPosition?: number;
-    /** Current front/rear view orientation */
-    view?: DeviceView;
-    /** Rack face orientation */
-    face?: DeviceView;
+    /** 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 */
@@ -437,7 +451,7 @@ interface NetworkNodeDataBase extends DeviceImageOptions {
     role?: string;
     /** Device width configuration */
     width?: Width | number;
-    /** Power port side for rear view */
+    /** Power port side for rear face */
     powerSide?: PowerSide;
     /** Vertical PDU height in centimeters */
     heightCm?: number;
@@ -545,7 +559,7 @@ interface NetworkNodeDataBase extends DeviceImageOptions {
     height?: number;
     headerHeight?: number;
     /** Optional precomputed map for handle-to-face resolution */
-    handleSideMap?: Record<string, DeviceView>;
+    handleSideMap?: Record<string, DeviceFace>;
     /** Additional extension metadata */
     metadata?: Record<string, unknown>;
 }
@@ -701,9 +715,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;
 };
+/**
+ * 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
@@ -759,15 +912,15 @@ 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 */
+    /** Power port side for rear face */
     powerSide?: PowerSide;
     /** Connected device IDs */
     connections?: string[];
@@ -935,36 +1088,43 @@ interface NetworkDiagramFlowMethods {
     getEdges: () => NetworkEdge[];
     fitView: (options?: NetworkDiagramFitViewOptions) => void;
 }
+/**
+ * Store state shape used by `NetworkDiagramStoreApi`.
+ * @public
+ */
+interface NetworkDiagramStoreState {
+    nodes: NetworkNode[];
+    edges: NetworkEdge[];
+    debug?: boolean;
+}
+/**
+ * Store connection validation parameters.
+ * @public
+ */
+interface NetworkDiagramValidateConnectionParams {
+    source: string | null;
+    target: string | null;
+    sourceHandle?: string | null;
+    targetHandle?: string | null;
+}
+/**
+ * Store connection validation result.
+ * @public
+ */
+interface NetworkDiagramValidationResult {
+    valid: boolean;
+    reason?: string;
+}
 /**
  * Store contract accepted by `NetworkDiagram`.
  * @public
  */
 interface NetworkDiagramStoreApi {
-    getState: () => {
-        nodes: NetworkNode[];
-        edges: NetworkEdge[];
-        debug?: boolean;
-    };
-    setState: (partial: Partial<{
-        nodes: NetworkNode[];
-        edges: NetworkEdge[];
-        debug?: boolean;
-    }>) => void;
-    subscribe: (listener: (state: {
-        nodes: NetworkNode[];
-        edges: NetworkEdge[];
-        debug?: boolean;
-    }) => void) => () => void;
+    getState: () => NetworkDiagramStoreState;
+    setState: (partial: Partial<NetworkDiagramStoreState>) => void;
+    subscribe: (listener: (state: NetworkDiagramStoreState) => void) => () => void;
     selectEdgeZIndex: (edge: NetworkEdge) => number;
-    validateConnection: (params: {
-        source: string | null;
-        target: string | null;
-        sourceHandle?: string | null;
-        targetHandle?: string | null;
-    }) => {
-        valid: boolean;
-        reason?: string;
-    };
+    validateConnection: (params: NetworkDiagramValidateConnectionParams) => NetworkDiagramValidationResult;
     selectNodeById: (id: string) => NetworkNode | undefined;
     selectConnectedEdges: (nodeId: string) => NetworkEdge[];
 }
@@ -973,6 +1133,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 */
@@ -1005,10 +1171,10 @@ interface NetworkDiagramProps {
     isValidConnection?: (connection: Connection) => boolean;
     /** Optional connection mode override */
     connectionMode?: ConnectionMode;
-    /** Callback when device view changes */
-    onViewChange?: (nodeId: string, view: DeviceView) => void;
+    /** Callback when a device face changes */
+    onFaceChange?: (nodeId: string, face: DeviceFace) => void;
     /** Callback when rack face changes */
-    onRackFaceChange?: (rackId: string, face: DeviceView) => void;
+    onRackFaceChange?: (rackId: string, face: DeviceFace) => void;
     /** CSS class name */
     className?: string;
     /** Inline styles */
@@ -1039,42 +1205,15 @@ interface NetworkDiagramProps {
     interaction?: NetworkDiagramInteractionOptions;
     /** Configuration for the floating action panel shown on selected rack/device nodes. */
     actionPanel?: NetworkDiagramActionPanelOptions;
-    /** Enable connecting edges by clicking on handles. When true, increases handle sizes for better touch targets. Default is true. */
-    connectOnClick?: boolean;
-    /** Disable panning on drag. Default is false. */
-    panOnDrag?: boolean;
-    /** Disable panning on scroll. Default is true. */
-    panOnScroll?: boolean;
-    /** Disable zooming on scroll. Default is true. */
-    zoomOnScroll?: boolean;
     /** Optional fitView options passed to React Flow */
     fitViewOptions?: FitViewOptions;
+    /**
+     * Let React Flow render only viewport-visible nodes and edges.
+     * Defaults to true, matching the library's existing large-diagram behavior.
+     */
+    onlyRenderVisibleElements?: boolean;
 }
 
-/**
- * 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 {
@@ -1085,7 +1224,7 @@ interface DiagramErrorBoundaryProps {
     /** Optional callback when an error is caught (e.g. for logging) */
     onError?: (error: Error, errorInfo: ErrorInfo) => void;
 }
-interface State {
+interface DiagramErrorBoundaryState {
     error: Error | null;
 }
 /**
@@ -1108,23 +1247,23 @@ interface State {
  * </DiagramErrorBoundary>
  * ```
  */
-declare class DiagramErrorBoundary extends Component<DiagramErrorBoundaryProps, State> {
-    state: State;
-    static getDerivedStateFromError(error: Error): State;
+declare class DiagramErrorBoundary extends Component<DiagramErrorBoundaryProps, DiagramErrorBoundaryState> {
+    state: DiagramErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): DiagramErrorBoundaryState;
     componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
     reset: () => void;
     render(): ReactNode;
 }
 
 interface RackNodeProps extends NodeProps<NetworkNode['data']> {
-    onViewChange?: (nodeId: string, view: 'front' | 'rear') => void;
+    onFaceChange?: (nodeId: string, face: 'front' | 'rear') => void;
     onRackFaceChange?: (rackId: string, face: 'front' | 'rear') => void;
     isDragOver?: boolean;
 }
 /**
  * Rack visualization component with U positioning support.
  *
- * Displays a 19" rack with configurable height, front/rear view switching,
+ * Displays a 19" rack with configurable height, front/rear face switching,
  * and support for mounting devices at specific U positions.
  *
  * @example
@@ -1194,12 +1333,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' }
+ *     ]
  *   }
  * }
  * ```
@@ -1275,9 +1411,7 @@ interface FibreFlowMapProps {
     className?: string;
     style?: React$1.CSSProperties;
     readOnly?: boolean;
-    panOnDrag?: boolean;
-    panOnScroll?: boolean;
-    zoomOnScroll?: boolean;
+    interaction?: NetworkDiagramInteractionOptions;
 }
 declare const FibreFlowMap: React$1.FC<FibreFlowMapProps>;
 
@@ -1418,6 +1552,14 @@ declare const inventoryToNetworkDiagram: (data: {
     nodes: NetworkNode[];
     edges: NetworkEdge[];
 };
+/**
+ * Convert inventory data directly into the canonical DiagramDocument model.
+ */
+declare const inventoryToDiagramDocument: (data: {
+    racks: InventoryRackDTO[];
+    devices: InventoryDeviceDTO[];
+    cables: InventoryCableDTO[];
+}) => DiagramDocument;
 /**
  * Generate simple layout positions for nodes array
  */
@@ -1446,6 +1588,14 @@ declare const netboxToNetworkDiagram: (data: {
     nodes: NetworkNode[];
     edges: NetworkEdge[];
 };
+/**
+ * Convert NetBox data directly into the canonical DiagramDocument model.
+ */
+declare const netboxToDiagramDocument: (data: {
+    racks: NetBoxRack[];
+    devices: NetBoxDevice[];
+    cables: NetBoxCable[];
+}, options?: NetBoxDeviceTransformOptions) => DiagramDocument;
 /**
  * Calculate U position for devices in a rack
  */
@@ -1963,18 +2113,91 @@ declare function addSpliceToTray(trays: SpliceTrayConfig[], trayId: string, spli
  */
 declare function removeSpliceFromTray(trays: SpliceTrayConfig[], trayId: string, spliceId: string): SpliceTrayConfig[];
 
-type PortFaces = {
+/**
+ * Normalize flat `DevicePort[]` input into explicit front/rear grouped blocks.
+ * This is the bridge between the recommended simple port schema and the
+ * lower-level grouped renderer input.
+ * @public
+ */
+declare function buildPortBlocksFromPorts(devicePorts: DevicePort[]): {
+    ports: PortBlock[];
+    rearPorts: PortBlock[];
+};
+/**
+ * Resolve the grouped front/rear port blocks from either supported input form:
+ * flat `ports: DevicePort[]` or explicit `portGroups` / `rearPortGroups`.
+ * @public
+ */
+declare function getResolvedPortBlocks(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): {
     ports: PortBlock[];
     rearPorts: PortBlock[];
 };
-type PortFaceData = Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'>;
-declare function buildPortBlocksFromPorts(devicePorts: DevicePort[]): PortFaces;
-declare function getResolvedPortBlocks(data: PortFaceData | undefined): PortFaces;
-declare function getFrontPortBlocks(data: PortFaceData | undefined): PortBlock[];
-declare function getRearPortBlocks(data: PortFaceData | undefined): PortBlock[];
-declare function hasFrontPorts(data: PortFaceData | undefined): boolean;
-declare function hasRearPorts(data: PortFaceData | undefined): boolean;
-declare function getDefaultDeviceView(data: PortFaceData | undefined): DeviceView;
+/**
+ * Resolve the front-facing grouped port blocks for a node/device data object.
+ * @public
+ */
+declare function getFrontPortBlocks(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): PortBlock[];
+/**
+ * Resolve the rear-facing grouped port blocks for a node/device data object.
+ * @public
+ */
+declare function getRearPortBlocks(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): PortBlock[];
+/**
+ * Determine whether a node/device data object resolves to any front ports.
+ * @public
+ */
+declare function hasFrontPorts(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): boolean;
+/**
+ * Determine whether a node/device data object resolves to any rear ports.
+ * @public
+ */
+declare function hasRearPorts(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): boolean;
+/**
+ * Choose the default device face based on the resolved front/rear port data.
+ * @public
+ */
+declare function getDefaultDeviceFace(data: Pick<NetworkNode['data'], 'ports' | 'portGroups' | 'rearPortGroups'> | undefined): DeviceFace;
+
+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?: DeviceFace;
+    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;
+
+type PortVisualKind = 'generic' | 'rj45' | 'sfp' | 'qsfp' | 'osfp' | 'console' | 'usb' | 'power_c13' | 'power_c19' | 'power_ac';
+interface PortVisualInput {
+    type?: PortType | string;
+    label?: string;
+    id?: string;
+    group?: string;
+    sourceTypeLabel?: string;
+    connectorType?: string;
+}
+interface PortVisualDimensions {
+    width: number;
+    height: number;
+    borderRadius: string;
+}
+declare function resolvePortVisualKind(input: PortVisualInput): PortVisualKind;
+declare function getStandardPortVisualDimensions(inputOrKind: PortVisualInput | PortVisualKind): PortVisualDimensions | undefined;
 
 /**
  * Power connector utilities for consistent styling across devices and PDUs
@@ -2307,6 +2530,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 +2555,7 @@ interface RawTemplatePort {
     type?: string;
     connectorType?: string;
     connector_type?: string;
-    position?: {
+    position?: string | {
         side?: string;
         offsetPercent?: number;
         offset_percent?: number;
@@ -2447,4 +2674,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 DeviceFace, type DeviceImageFit, type DeviceImageOptions, type DeviceImageRepeat, DeviceNode, type DeviceNodeData, DevicePlacementError, type DevicePlacementValidation, type DevicePort, type DeviceStatus, type DeviceTemplateV2, type DiagramDocument, type DiagramEdge, type DiagramEdgeEndpoint, type DiagramEndpoint, DiagramErrorBoundary, type DiagramErrorBoundaryProps, type DiagramErrorBoundaryState, type DiagramExternalRef, type DiagramNode, type DiagramNodeKind, type DiagramNodePlacement, type DiagramNodeRender, type DiagramUiState, type EndpointConnectionKind, type EndpointMetadata, FIBER_COLORS_12, type FiberCable, type FiberCableType, type FiberColorId, FiberEdge, FiberNode, FibreCableWithTubesExpanded, type FibreCableWithTubesExpandedProps, type FibreFlowCable, type FibreFlowCableKind, type FibreFlowCableLayout, type FibreFlowCableNodeData, type FibreFlowCircuit, type FibreFlowClosure, type FibreFlowClosureNodeData, type FibreFlowColorMode, type FibreFlowEndpoint, type FibreFlowLayoutDirection, FibreFlowMap, type FibreFlowMapProps, type FibreFlowRow, type FibreFlowSplice, type FibreFlowTubeLabel, FibreSplitNode, HANDLE_EXTENSION_PX, type InventoryCableDTO, type InventoryDeviceDTO, type InventoryRackDTO, type MountClass, MultiTubeCableNode, type NetBoxCable, type NetBoxDevice, type NetBoxDeviceTransformOptions, type NetBoxInterface, type NetBoxMappedPort, type NetBoxPortPosition, type NetBoxRack, NetworkDiagram, type NetworkDiagramActionPanelOptions, type NetworkDiagramFitViewOptions, type NetworkDiagramFlowMethods, type NetworkDiagramFlowObject, type NetworkDiagramInteractionOptions, type NetworkDiagramOptions, type NetworkDiagramProps, type NetworkDiagramState, type NetworkDiagramStore, type NetworkDiagramStoreApi, type NetworkDiagramStoreState, type NetworkDiagramToImageOptions, type NetworkDiagramValidateConnectionParams, type NetworkDiagramValidationResult, type NetworkEdge, type NetworkEdgeData, type NetworkEdgeType, type NetworkGraphSnapshot, type NetworkNode, type NetworkNodeData, type NetworkNodeDataBase, type NetworkNodeDataByType, type NetworkNodeType, PANEL_BORDER_WIDTH, PANEL_HEADER_HEIGHT, PANEL_HEIGHT_PX, PANEL_PADDING, PANEL_TUBE_TRAY_SPACING, PANEL_WIDTH_PX, POWER_CONNECTORS, PatchPanelNode, type Port, type PortBlock, type PortCableType, type PortPosition, type PortType, type PortVisualDimensions, type PortVisualInput, type PortVisualKind, type PowerConnectorConfig, PowerEdge, type PowerPortStyle, type PowerSide, RACK_HEADER_HEIGHT, RACK_WIDTH_PX, type RackConfig, type RackDevice, type RackDeviceType, type RackLayoutMode, type RackMountMode, type RackMountedNodeType, RackNode, type RackNodeData, type RackNodeProps, type RackSchemaOptions, type RawNetboxTemplate, type RawTemplatePort, type RawTemplatePortBlock, type ReplaceEdgeOptions, type SpliceConfig, SpliceNode, SplicePlacementError, type SplicePlacementValidation, type SpliceSchemaOptions, type SpliceTrayConfig, SpliceTrayNode, TEMPLATE_SCHEMA_VERSION, type TemplateFaceData, type TemplateFrontRearPortLink, type TemplateParseResult, type TemplatePort, type TemplatePortBlock, type TemplateSource, type TemplateValidationIssue, type TemplateValidationReport, type TemplateWidth, TubeNode, type UNumberingDirection, U_HEIGHT_PX, type ValidateConnectionParams, type ValidationResult, VerticalPDU, Width, addDeviceToRack, addSpliceToTray, 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, getDefaultDeviceFace, getDeviceConnectorType, getEndpointMetadata, getFiberColor, getFrontPortBlocks, getInnerContentWidth, getPDUPortType, getPanelHeight, getPanelWidth, getPowerPortStyle, getRackBounds, getRearPortBlocks, getResolvedPortBlocks, getStandardPortVisualDimensions, getStatusColor, getTrayDimensions, getTubeDimensions, hasFrontPorts, hasRearPorts, inventoryCableToNetworkEdge, inventoryDeviceToNetworkNode, inventoryRackToNetworkNode, inventoryToDiagramDocument, inventoryToNetworkDiagram, isHighPowerConnector, isPointInRack, isStriped, isUPositionAvailable, netboxCableToNetworkEdge, netboxDeviceToNetworkNode, netboxRackToNetworkNode, netboxToDiagramDocument, netboxToNetworkDiagram, networkGraphToDiagramDocument, parseNetboxTemplate, removeDeviceFromRack, removeSpliceFromTray, replaceEdge, resolveEndpointCompatibilityKeys, resolvePortVisualKind, snapToCouplerPosition, snapToSplicePosition, snapToUPosition, updateDeviceUPosition$1 as updateDeviceUPosition, updateDeviceUPosition as updateDeviceUPositionInSchema, updateSpliceHolderPosition, useEdges as useDiagramEdges, useNodes as useDiagramNodes, useNetworkDiagram, validateAndSnapDevice, validateRackDevicePlacements, validateRenderFidelity, validateSplicePlacements };