ZeroSpace/.junie/plans/add-galaxy-map-and-ui-improvements.md

sessionId

sessionId
session-260928-131223-1ueu

Requirements

Overview & Goals

The goal of this initiative is to elevate the UI and user experience of ZeroSpace.Web and introduce an interactive Galaxy Map page. The Galaxy Map will visually display all planetary nodes positioned by their coordinates (X, Y), render connection lines between interconnected systems, and provide instant hover information popups detailing yields, occupation buffs, masteries, and faction classifications.

Scope

In Scope

• Galaxy Page (/galaxy): Interactive star map rendering all 78 star systems from StarSystems.All with their actual (X, Y) spatial coordinates.
• Connection Lines: Drawing connection paths between systems based on StarSystemData.ConnectedSystems.
• Hover Information Popup: Dynamic floating tooltip/card showing system name, kind, occupation buffs, system masteries, yield bonuses, and connections.
• Click Navigation: Direct navigation from galaxy nodes to /StarSystem/{Id} details page.
• UI & Aesthetic Overhaul:
  • Updating NavMenu.razor with a dedicated Galaxy Map entry and modern styling.
  • Revamping Home.razor from default template placeholder to an engaging sci-fi overview dashboard.
  • Enhancing theme colors, badge indicators, cards, and typography in app.css.

Out of Scope

• Backend database schema modifications (uses existing static/generated ZeroSpace.Model records).
• Real-time multiplayer synchronization or editing capabilities (map editing remains in ZeroSpace.MapEditor).

User Stories

• As a player / wiki reader, I want to view a visual galaxy map with all planetary nodes and connections so that I can understand system layout and routes across the galaxy.
• As a player, I want to hover over any planetary node to immediately see its occupation buff, yields, and system mastery without having to navigate to separate pages.
• As a user, I want to click on a star system node on the map to navigate directly to its detailed page.
• As a user, I want a sleek, cohesive dark sci-fi web interface with clear navigation and a functional dashboard.

Functional Requirements

1. Galaxy Map Rendering:
   • The map shall render an SVG canvas encompassing coordinate bounds (0 to 1000) preserving aspect ratio.
   • Lines must connect every system with its entries in ConnectedSystems without duplicate edge rendering.
   • Planetary nodes shall be rendered as circular nodes styled and colored according to StarSystemKind:
     • Homeworld: Vibrant Emerald / Green (#43a047 / #10b981)
     • Core: Vibrant Amber / Orange (#fb8c00 / #f59e0b)
     • Side: Vibrant Sky Blue / Cyan (#4a90d9 / #38bdf8)
2. Hover Information Popup:
   • Hovering over a planet node triggers a floating information popup.
   • Popup content includes:
     • Planet Name & Kind badge
     • Occupation buff (e.g. +50 Starting Hexite)
     • System mastery name (if present)
     • Higher yield indicators (Influence, Credits, Energy, Items)
     • Count and list of connected star systems
   • Tooltip disappears smoothly when the cursor leaves the node.
3. Map Interaction:
   • Hovering a node highlights the node (glow ring) and highlights incoming/outgoing connection lines.
   • Clicking a node navigates to /StarSystem/{Id}.
4. App Navigation & Home Page:
   • NavMenu.razor includes a link to /galaxy labeled "Galaxy Map" with an appropriate icon.
   • Home.razor provides quick-launch cards to Galaxy Map, Star Systems, Masteries, and Units with summary counts.

Non-Functional Requirements

• Performance: Instant SVG rendering with zero lag for 78 nodes and ~200 connections; pure CSS/Blazor event handling with no external heavy mapping dependencies.
• Responsiveness: Map scales smoothly inside its container across desktop and mobile screens.
• Accessibility: Clear contrast ratios, readable tooltips, and keyboard/touch support for node selection.

Technical Design

Current Implementation

• ZeroSpace.Model.StarSystems.All: Contains all 78 star systems with records containing Id, Name, Kind, X, Y, ConnectedSystems, OccupationBuff, SystemMastery, and yield flags.
• ZeroSpace.Web: Blazor WebAssembly application using Bootstrap 5 and Telerik Blazor components.
• Existing pages include StarSystemIndex.razor, StarSystemDetail.razor, SystemMasteryIndex.razor, and Units.razor.
• Home.razor is currently a default "Hello World" template placeholder.

Key Decisions

1. SVG Vector Graphics for Galaxy Map:
   • Chosen Approach: Native Blazor SVG rendering (<svg viewBox="0 0 1000 1000">).
   • Rationale: SVG offers vector sharpness at all display resolutions, reactive Blazor event binding (@onmouseenter, @onmouseleave, @onclick), lightweight footprint, and zero external JS dependency overhead.
2. Dynamic Overlay Tooltip:
   • Chosen Approach: HTML/CSS floating glassmorphism card positioned relative to the hovered node/cursor with smooth fade transition.
   • Rationale: Allows rich formatting (badges, icons, multi-column yields) and styling that matches the dark sci-fi aesthetic better than native SVG <title> or basic browser tooltips.
3. Connection Line Optimization:
   • Chosen Approach: Precompute unique undirected edge pairs (From, To) on initialization.
   • Rationale: Prevents duplicate overlapping lines between reciprocal connections A -> B and B -> A, improving render performance and visual clarity.

Proposed Architecture & Flow

graph TD
    Nav[NavMenu.razor] -->|Navigate /galaxy| GalaxyPage[Galaxy.razor]
    Home[Home.razor] -->|Quick Link| GalaxyPage
    
    subgraph Galaxy.razor
        Model[StarSystems.All] --> EdgeBuilder[Connection Deduplicator]
        EdgeBuilder --> SVGCanvas[SVG Canvas ViewBox 0 0 1000 1000]
        Model --> NodeRenderer[Node Elements & Coordinates]
        
        SVGCanvas --> Lines[SVG Lines: Connection Paths]
        SVGCanvas --> Nodes[SVG Circles & Glows: Planets]
        
        Nodes -->|@onmouseenter| HoverState[Hovered System State]
        Nodes -->|@onclick| NavAction[NavigationManager.NavigateTo /StarSystem/Id]
        
        HoverState --> Popup[Floating Planet Info Card]
    end

Components & File Structure

• New Files:
  • ZeroSpace.Web/Pages/Galaxy.razor: Main Galaxy map page containing the SVG viewport, control header, node filtering/legend, and popup overlay.
  • ZeroSpace.Web/Pages/Galaxy.razor.css: Scoped styles for map container, SVG glow effects, connection styling, and animated hover card.
• Modified Files:
  • ZeroSpace.Web/Layout/NavMenu.razor: Add "Galaxy Map" item with navigation icon.
  • ZeroSpace.Web/Pages/Home.razor: Overhaul into a sci-fi hub with hero banner and feature cards.
  • ZeroSpace.Web/wwwroot/css/app.css: Dark sci-fi styling improvements, badge colors, and glassmorphism utilities.

Data Models / Contracts

public sealed record ConnectionEdge(
    StarSystemData From,
    StarSystemData To);

public sealed class GalaxyMapState
{
    public IReadOnlyList<StarSystemData> Systems { get; set; } = StarSystems.All;
    public IReadOnlyList<ConnectionEdge> Connections { get; set; } = [];
    public StarSystemData? HoveredSystem { get; set; }
    public double TooltipX { get; set; }
    public double TooltipY { get; set; }
    public string? SelectedKindFilter { get; set; }
}

Risks & Mitigations

• Tooltip overflow near screen edges: Clamp calculated tooltip coordinates within container boundaries to prevent viewport clipping.
• Coordinate overlap on small screens: Ensure viewBox preserves 1:1 aspect ratio (preserveAspectRatio="xMidYMid meet") and allow zooming/scaling via standard CSS/viewport responsiveness.

Testing

Validation Approach

Verification will be performed through build checks, component markup analysis, and interactive scenario validation in the Blazor runtime.

Key Scenarios

1. Galaxy Map Rendering:
   • Verify that all 78 star systems are rendered at their designated (X, Y) positions.
   • Verify that connection lines accurately connect linked systems without orphaned or broken lines.
   • Verify node color coding matches StarSystemKind (Homeworld, Core, Side).
2. Hover Information Popup:
   • Hovering over a planet node displays the popup immediately.
   • Verify all fields render accurately (Occupation buff, System mastery, Yields, Connected systems list).
   • Moving the mouse away dismisses the popup cleanly.
3. Navigation & Interactivity:
   • Clicking a node navigates to the corresponding /StarSystem/{Id} route.
   • Navigating via the "Galaxy Map" link in NavMenu.razor loads the page properly.
4. UI & Responsiveness:
   • Verify Home.razor renders updated dashboard cards and quick links.
   • Verify dark-theme sci-fi visual style across desktop and smaller browser viewports.

Regressions & Edge Cases

• Star systems without occupation buffs or masteries display clean fallback dashes (—) without layout breaks.
• Rapid mouse movements over adjacent nodes update the hover popup smoothly without flickering.

Delivery Steps

✓ Step 1: Implement Galaxy Map SVG rendering and connection lines

A functional SVG-based Galaxy Map page (Galaxy.razor) renders all star system nodes and connection lines based on their world coordinates.

• Create ZeroSpace.Web/Pages/Galaxy.razor with route @page "/galaxy" and navigation title.
• Parse StarSystems.All to extract unique undirected connection pairs and planetary node coordinate models.
• Render connection lines (<line>) in SVG with dark-steel futuristic line styling (#3a4d6b, opacity, glow).
• Render planetary nodes (<circle> / <g>) positioned at (system.X, system.Y) using color coding based on StarSystemKind (Homeworld = green, Core = orange/amber, Side = blue/cyan).
• Add SVG viewBox scaling (e.g. 0 0 1000 1000) and responsive container layout to ensure crisp vector rendering on all screen sizes.
• Implement click handlers on nodes to navigate directly to /StarSystem/{Id}.

✓ Step 2: Implement dynamic planetary hover popup and interactive highlights

Interactive hover tooltip overlays display rich star system details when the user hovers over any planet node on the galaxy map.

• Design a floating glassmorphism hover card component / markup positioned dynamically relative to the active node or cursor.
• Display star system metadata: system name, Kind badge, OccupationBuff, SystemMastery link, and Yield bonuses (Influence, Credits, Energy, Items).
• Add highlight visual effects when hovering over a node (pulsing glow radius, highlight connected lines).
• Handle edge cases such as tooltip boundary clamping near viewport edges and debounced mouse enter/leave events.

✓ Step 3: Refine global UI, navigation menu, and dashboard landing page

ZeroSpace.Web navigation, Home landing dashboard, and global UI styles are updated to match a polished sci-fi space aesthetic.

• Update ZeroSpace.Web/Layout/NavMenu.razor with a dedicated "Galaxy Map" navigation link with custom star/galaxy icon.
• Transform ZeroSpace.Web/Pages/Home.razor into an overview hub showcasing quick links and summary stats for Galaxy Map, Star Systems, System Masteries, and Units.
• Enhance ZeroSpace.Web/wwwroot/css/app.css and component stylesheets with refined dark-theme colors, glassmorphism cards, glowing badges, and smooth hover transitions.
• Verify solution builds cleanly and all navigation flows between the Galaxy map, system details, and other pages work seamlessly.