System Map Canvas

Turn services, databases, queues and external dependencies into an architecture diagram people can actually operate. Give it node and edge data and the component lays the nodes out in layers following the edge direction, on a blueprint-style grid with semantic edge colors and a legend. Drag to pan, scroll or pinch to zoom, and expand a group into a frame or collapse it back into a single card (edges into a collapsed group reconnect to the group itself). Select any node and its edges and neighbors stay sharp while everything else fades to 25%; a details panel slides in from the right listing upstream and downstream nodes, one click away. A minimap and a "fit to view" button sit in the bottom-right corner.

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<SystemMapCanvas/>

    </div>
  );
}

Installation

Usage

import {
  SystemMapCanvas,
  type SystemMapEdge,
  type SystemMapNode,
} from "@/components/ui/system-map-canvas";

const nodes: SystemMapNode[] = [
  { id: "web", label: "Web 用戶端", kind: "client" },
  { id: "gateway", label: "API Gateway", kind: "service" },
  { id: "orders", label: "訂單域", kind: "group" },
  { id: "order", label: "訂單服務", kind: "service", parent: "orders" },
  { id: "queue", label: "通知佇列", kind: "queue", parent: "orders" },
  { id: "db", label: "主資料庫", kind: "database", description: "訂單的唯一真實來源" },
];

const edges: SystemMapEdge[] = [
  { from: "web", to: "gateway", kind: "sync", label: "HTTPS" },
  { from: "gateway", to: "order", kind: "sync" },
  { from: "order", to: "queue", kind: "async", label: "訂單事件" },
  { from: "order", to: "db", kind: "data" },
  { from: "order", to: "gateway", kind: "error" },
];

<SystemMapCanvas
  nodes={nodes}
  edges={edges}
  defaultExpanded={["orders"]}
  edgeStyle="curved"
  onSelectedChange={(id) => console.log("selected", id)}
/>;

The sample labels are Traditional Chinese: 用戶端 (client), 訂單域 (orders domain), 訂單服務 (order service), 通知佇列 (notification queue), 主資料庫 (primary database), 訂單事件 (order event).

Props

SystemMapNode

SystemMapEdge

SystemMapNodeKind, SystemMapEdgeKind and SystemMapCanvasProps are exported as named types as well.

CSS variables

How it works

• Self-written layered layout: with layout="auto", each node's column comes from its topological depth along the edges, and every column is reordered with four alternating barycenter sweeps to reduce crossings. Clients (kind="client") are always treated as entry points in the leftmost column, error edges are drawn but not used for layering, and any remaining cycles are broken by skipping DFS back edges, so feedback loops do not skew the whole map
• Groups are laid out recursively: an expanded group lays out its own children first, then joins the parent level as one large node, so group frames never overlap outside nodes. A collapsed group turns back into a single card; edges into any node inside it reconnect to the group, and duplicate edges merge into one
• Expand animation: children spread out from the group's center to their layout positions on a spring (stiffness 260, damping 26), with edge paths interpolating alongside; collapsing reverses this back into the group card
• Pan and zoom: drag the background to pan (pointer capture); the wheel zooms around the cursor, and trackpad pinch (ctrl + wheel) and two-finger touch work too. Moves from buttons, keys and the wheel are smoothed by a spring (stiffness 300, damping 35), while dragging tracks the pointer directly. The background grid follows the zoom, with a major line every 5 minor cells
• Minimap: shows every visible node plus the current view frame; drag the frame to move the view, or click outside it to recenter there first
• The async dash flow only animates while the component is on screen and pauses once it scrolls away

Accessibility

• The outer element is role="application" with aria-roledescription="系統架構圖" (system map) and an aria-describedby pointing at the usage instructions
• The canvas is focusable: arrow keys pan by 40px, + / - zoom, and 0 fits the view. Tab visits every node (button) in column order, and focusing a node outside the view pans it into view
• Enter selects a node, Space on a group expands or collapses it, and Esc clears the selection and closes the details panel. Each node's aria-label includes its name, kind and upstream / downstream counts (for example "付款服務，服務，1 個上游，2 個下游" — payment service, service, 1 upstream, 2 downstream)
• A sr-only list of nodes and edges is also provided, reading each edge as "source to target, kind: label"
• Every button has a focus-visible ring; the legend and minimap are visual aids only (aria-hidden)
• When the user's system has reduce motion turned on, async edges become static dashes that do not flow, and panning, zooming, expanding, collapsing and the details panel all jump straight to their end state