Files
pipelines/app/lib/features/graph/routing/route_models.dart
T
alan b381290f34 feat(app): add deterministic orthogonal graph edge routing
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.
2026-10-21 16:51:38 +01:00

262 lines
6.8 KiB
Dart

/// Pure orthogonal geometry for a workflow graph's edges and labels.
///
/// The caller owns every measurement: node boxes come from the landed
/// `GraphLayout`, label extents are measured after text layout, and clearances
/// or spacings come from [RoutingConfig]. This library never assumes a font,
/// widget style, device class or CSS value, and it has no Flutter imports.
///
/// The same result can be built into a painter, native widgets or a test
/// fixture; no drawing decision lives here.
library;
export 'routing_inputs.dart';
/// One point on an orthogonal route, in graph space.
class RoutePoint {
const RoutePoint(this.x, this.y);
final double x;
final double y;
@override
bool operator ==(Object other) =>
other is RoutePoint && other.x == x && other.y == y;
@override
int get hashCode => Object.hash(x, y);
@override
String toString() => 'RoutePoint($x, $y)';
}
/// The border an edge leaves or enters through.
enum RoutePortSide { top, right, bottom, left }
/// A route endpoint on a node's border.
///
/// [side] is the edge's outward direction: a right port leaves to the right
/// (or enters from the right), a left port leaves to the left, and so on.
class RoutePort {
const RoutePort({required this.side, required this.point});
final RoutePortSide side;
final RoutePoint point;
@override
bool operator ==(Object other) =>
other is RoutePort && other.side == side && other.point == point;
@override
int get hashCode => Object.hash(side, point);
@override
String toString() => 'RoutePort($side, ${point.x}, ${point.y})';
}
/// How an edge relates to the layer it comes from.
enum RouteKind {
/// The target is in a later rank.
forward,
/// Both endpoints share a rank (a cycle or strongly connected component).
sameRank,
/// The target is in an earlier rank. Ranks from `assignGraphRanks` only
/// produce this for a caller-supplied layout; it is still routed honestly.
back,
/// The source and target are the same node.
selfLoop,
}
/// Why an edge has no route.
enum RouteSkipReason {
/// The source key has no placed node.
unknownSource,
/// The target key has no placed node, including an empty/unknown target.
unknownTarget,
}
/// One edge's deterministic orthogonal route.
///
/// [id], [source], [outcome], [target], [label] and [fallback] are copied from
/// the definition edge unchanged. [points] starts at [sourcePort] and ends at
/// [targetPort]; every consecutive pair shares one coordinate.
class EdgeRoute {
EdgeRoute({
required this.id,
required this.source,
required this.outcome,
required this.target,
required this.label,
required this.fallback,
required this.kind,
required this.straight,
required this.sourcePort,
required this.targetPort,
required List<RoutePoint> points,
}) : points = List.unmodifiable(points);
final int id;
final String source;
final String outcome;
final String target;
final String label;
final bool fallback;
final RouteKind kind;
/// True when the route is one straight horizontal segment.
final bool straight;
final RoutePort sourcePort;
final RoutePort targetPort;
final List<RoutePoint> points;
@override
bool operator ==(Object other) =>
other is EdgeRoute &&
other.id == id &&
other.source == source &&
other.outcome == outcome &&
other.target == target &&
other.label == label &&
other.fallback == fallback &&
other.kind == kind &&
other.straight == straight &&
other.sourcePort == sourcePort &&
other.targetPort == targetPort &&
_samePoints(other.points, points);
@override
int get hashCode => Object.hash(
id,
source,
outcome,
target,
label,
fallback,
kind,
straight,
sourcePort,
targetPort,
Object.hashAll(points),
);
}
/// One measured label box placed clear of node interiors.
class EdgeLabelBox {
const EdgeLabelBox({
required this.edgeId,
required this.x,
required this.y,
required this.width,
required this.height,
});
final int edgeId;
final double x;
final double y;
final double width;
final double height;
double get right => x + width;
double get bottom => y + height;
@override
bool operator ==(Object other) =>
other is EdgeLabelBox &&
other.edgeId == edgeId &&
other.x == x &&
other.y == y &&
other.width == width &&
other.height == height;
@override
int get hashCode => Object.hash(edgeId, x, y, width, height);
}
/// An edge the router deliberately did not draw.
///
/// The definition identity is preserved so a caller can present a diagnostic
/// instead of inventing a node, route or visit.
class RouteDiagnostic {
const RouteDiagnostic({
required this.id,
required this.source,
required this.outcome,
required this.target,
required this.reason,
required this.message,
});
final int id;
final String source;
final String outcome;
final String target;
final RouteSkipReason reason;
final String message;
@override
bool operator ==(Object other) =>
other is RouteDiagnostic &&
other.id == id &&
other.source == source &&
other.outcome == outcome &&
other.target == target &&
other.reason == reason &&
other.message == message;
@override
int get hashCode => Object.hash(id, source, outcome, target, reason, message);
}
/// The complete immutable routing result.
///
/// [width] and [height] include every route point and label box as well as the
/// landed layout bounds, so a loop that leaves the node grid expands the
/// returned box instead of being clipped. [routes] and [skipped] are ordered by
/// definition edge id; [labels] follows the same order.
class GraphRouting {
GraphRouting({
required List<EdgeRoute> routes,
required List<EdgeLabelBox> labels,
required List<RouteDiagnostic> skipped,
required this.width,
required this.height,
}) : routes = List.unmodifiable(routes),
labels = List.unmodifiable(labels),
skipped = List.unmodifiable(skipped);
final List<EdgeRoute> routes;
final List<EdgeLabelBox> labels;
final List<RouteDiagnostic> skipped;
final double width;
final double height;
bool get isEmpty => routes.isEmpty;
/// The route for [id], or null when that edge was skipped.
EdgeRoute? routeFor(int id) {
for (final route in routes) {
if (route.id == id) return route;
}
return null;
}
/// The label box for [id], or null when the edge was skipped.
EdgeLabelBox? labelFor(int id) {
for (final label in labels) {
if (label.edgeId == id) return label;
}
return null;
}
}
bool _samePoints(List<RoutePoint> a, List<RoutePoint> b) {
if (a.length != b.length) return false;
for (var index = 0; index < a.length; index += 1) {
if (a[index] != b[index]) return false;
}
return true;
}