spike: port layout algorithm for high-density devices

[ggfevans]

Parent Epic

Part of #71 (Network Interface Visualization and Connectivity)

Summary

Research and design a port layout algorithm that handles high-density devices (48+ ports) within the constrained device width.

Problem Statement

• 1U device interior width: ~186px (19" rack)
• 48 ports × 8px spacing = 384px needed
• Won't fit in single row!

Research Areas

• Multi-row port layout (e.g., 2 rows of 24)
• Stacked ports (offset front/back rows)
• Dynamic spacing based on port count
• Threshold-based grouping (group when > N ports)
• Port size scaling at different densities

Acceptance Criteria

• Document algorithm with diagrams
• Define thresholds: when to use single-row vs multi-row vs grouped
• Ensure minimum touch target size (44px) is achievable on mobile
• Consider zoom-level behavior

Technical Constraints

• Must work for 10" rack (narrower) and 19" rack
• Must work for 0.5U to 4U+ devices
• Must maintain port identification (hover/click accuracy)

References

• Spike research: spike: Network interface visualization research #237, PR docs: network interface visualization spike research (#237) #242
• Prototype: docs/research/prototype-port-indicators.svelte

[ggfevans]

Spike Complete

Research deliverables for port layout algorithm on high-density devices.

Key Findings

The Problem:

• 48 ports × 8px spacing = 384px needed
• 19" rack interior = 186px (insufficient)

The Solution: Multi-row layout (industry standard)

• 2 rows of 24 ports for 48-port devices
• 186px ÷ 24 = 7.75px per port (achievable)

Additional Strategies:

• Zoom-aware rendering (hide <0.5x, group 0.5-1.0x, individual >1.0x)
• Touch accessibility via 44×44px invisible overlays
• 10" rack uses more aggressive grouping

Deliverables

Research PR: #361

• docs/research/spike-248-port-layout-algorithm.md (main synthesis)
• docs/research/248-codebase.md
• docs/research/248-external.md
• docs/research/248-patterns.md

Implementation Issues:

1. feat: port layout algorithm with multi-row support #356 - Port layout algorithm with multi-row support
2. feat: port render modes (individual and grouped) #357 - Port render modes (individual and grouped)
3. feat: zoom-aware port rendering thresholds #358 - Zoom-aware port rendering thresholds
4. feat: touch-accessible port overlays #359 - Touch-accessible port overlays
5. feat: 10-inch rack port layout optimizations #360 - 10-inch rack port layout optimizations

Summary

The research confirms that multi-row layout is the correct approach, matching how physical hardware (Ubiquiti, Cisco, etc.) arranges 48-port switches. The algorithm should be zoom-aware, falling back to grouped badges at low zoom levels. Touch accessibility is solved via invisible overlay buttons rather than enlarging visual ports.