Pure-Dart P2c slice: interval-aware ports and corridors, label-aware lane spacing, measured label placement with fallback shelf, skipped diagnostics and routing bounds. 20 focused tests plus existing suite and web build pass.
6.8 KiB
P2c — deterministic orthogonal edge and label routing
What changed
New app-only, pure-Dart files. No existing file, server, web client, legacy
client, shell, main.dart, pubspec, domain, layout, other feature or platform
source was edited.
| File | Lines | Responsibility |
|---|---|---|
lib/features/graph/routing/route_models.dart |
261 | public route, port, label, diagnostic and bounds types |
lib/features/graph/routing/routing_inputs.dart |
64 | measured label extents and caller clearances |
lib/features/graph/routing/route_geometry.dart |
175 | axis track allocator and column-gap bands |
lib/features/graph/routing/corridor_plan.dart |
105 | vertical corridor allocation per column gap |
lib/features/graph/routing/edge_route_planner.dart |
265 | forward/back/same-rank/self-loop polyline planning |
lib/features/graph/routing/edge_label_placement.dart |
175 | measured label boxes clear of nodes and other labels |
lib/features/graph/routing/graph_edge_routing.dart |
135 | validation, skipped diagnostics, labels, total bounds |
test/features/graph/routing/routing_fixtures.dart |
143 | chain/diamond/parallel/cycle/self-loop/disconnected fixtures |
test/features/graph/routing/routing_assertions.dart |
215 | orthogonality, borders, node interiors, corridors, labels, bounds |
test/features/graph/routing/graph_edge_routing_test.dart |
191 | chain, diamond, parallel, cycle, loop, disconnected, expanded text, unknown targets |
test/features/graph/routing/graph_routing_geometry_test.dart |
161 | wide labels, tight gaps, 3-stage SCC, backward layout, loop + forwards |
test/features/graph/routing/graph_routing_validation_test.dart |
222 | empty input, missing measurements, duplicate ids, invalid config, determinism/immutability |
No painting, widgets, styling, shell wiring or font/CSS/device constants were added.
Public API
GraphRouting routeGraphEdges({
required GraphLayout layout,
required List<GraphEdge> edges,
required Map<int, LabelExtent> labelExtents,
required RoutingConfig config,
});
RoutingConfig takes nodeClearance, laneSpacing, corridorSpacing,
portSpacing, labelGap and optional boundsPadding. LabelExtent is the
caller's measured label width/height. The node boxes and ranks are the landed
GraphLayout values; the router never moves or resizes a node.
GraphRouting exposes unmodifiable routes, labels, skipped, width and
height, plus routeFor(id) / labelFor(id). Each EdgeRoute keeps the
definition id, source, outcome, target, label and fallback flag, and
returns sourcePort, targetPort, a RouteKind and an orthogonal points
list. Each EdgeLabelBox carries the measured box for its edge id.
Deterministic guarantees (and what is not claimed)
- Identity: routed edges copy the definition identity unchanged; skipped
edges keep it in
RouteDiagnosticwithunknownSource/unknownTarget. No node, route or visit is invented for an empty, missing or unknown target. - Order and stability: routes, labels and diagnostics are ordered by edge id regardless of input order. Equal input produces equal, immutable results.
- Orthogonality and ports: every consecutive point pair shares one coordinate. Endpoints are exactly on the source/target border with the recorded side: forward routes leave right and enter left; same-rank, backward and self-loop routes leave/enter the right side.
- Node avoidance: a forward one-rank route is a straight horizontal run only when the boxes share a port band and leave room for label-aware track spacing. Every other route drops into a unique horizontal lane below the node grid, travels vertically only inside column gaps (or the free space right of the last column), and returns to a port through its own stub. Vertical corridors and lanes never enter a node column, and every horizontal stub stays on a row that is clear of unrelated node boxes.
- Distinguishable runs: vertical tracks are spread across each gap, one slot per corridor request; horizontal stubs and straight routes share one interval-aware allocator; every wrapping route owns its own lane. Two edges cannot share a collinear run in the tested fixtures.
- Labels: each routed edge needs a measured
LabelExtent; a missing one is anArgumentError. The box is placed at a deterministic route run, clear of node interiors and earlier labels. If a run is too narrow (for example a wide label between close columns), the label moves to a free shelf below the drawing and the returned bounds grow instead of covering a node. - Bounds:
width/heightinclude the landed node layout, all route points and all label boxes, plusboundsPadding. A self loop or an edge into the right-free gap expands the box; nothing is clipped. - Not claimed: perfect general crossing minimization or minimal bend counts. Corridors and lanes are deterministic and locally separated, not a globally optimal routing.
Checks actually run
flutter pub get
dart format lib/features/graph/routing test/features/graph/routing # 0 changed
flutter test test/features/graph/routing # 20 passed
flutter analyze # No issues found!
flutter test # 193 passed
Focused coverage includes chain, diamond fan-out/fan-in, three outcomes to one target, a two-stage and a three-stage SCC, a self loop alone and beside forward routes, disconnected stages, heterogeneous widths, 2.6x expanded text, tight gaps, wide labels, a caller-supplied backward rank, missing/empty/unknown targets, immutability, stable ordering and finite bounds.
Honest limits
- No rendering. This is a nonvisual geometry slice: no painter, widgets, native controls, screenshots or browser behavior. Rendered parity belongs to the next renderer task.
- Layout is an input. The router does not widen columns for labels or move nodes. Very wide labels may sit on the free shelf below the drawing; callers that want labels beside an edge should reserve enough column gap when laying out nodes. A zero-width column gap leaves no space for distinct vertical corridors, so callers should supply a positive gap (the landed layout keeps whatever gap it is given).
- No general crossing optimum. Only deterministic corridor/lane separation is guaranteed, as described above.
- No server or device. Tests use local fixtures only; no run, pipeline, schedule, service, emulator, ADB, Android/iOS build or live chat was touched.
- Mobile unverified. Only web-targeted Flutter test/analyze ran.
- Uncommitted candidate. Per this stage's instruction the slice is left in the worktree; no commit, push or deployment was made.