Files
alan c1f140bc78 feat(app): add deterministic content-sized graph node layout
Pure-Dart SCC ranking and column placement over the landed graph
identities. Every extent and gap is caller supplied; missing
measurements are rejected rather than defaulted.

Focused tests cover linear, diamond, cycle, self-loop, disconnected,
terminal, expanded-text and invalid-input cases.
2026-10-21 16:25:17 +01:00

130 lines
3.8 KiB
Dart

/// Pure geometry for a workflow graph's node layout.
///
/// Every size and gap is supplied by the caller. The native renderer measures
/// each node after text layout (including the platform's text scaling), so this
/// library never assumes a node width, font, palette or device class.
///
/// No Flutter imports: rectangles are plain numbers so the same result can be
/// built into widgets, a canvas or a test fixture.
library;
void _requireFiniteNonNegative(String name, double value) {
if (!value.isFinite || value < 0) {
throw ArgumentError.value(value, name, 'must be finite and non-negative');
}
}
/// One caller-measured node extent, in logical pixels.
///
/// A width or height may be zero for an empty label; the layout still keeps the
/// node separate from its neighbours through the configured gaps.
class NodeExtent {
NodeExtent({required this.width, required this.height}) {
_requireFiniteNonNegative('width', width);
_requireFiniteNonNegative('height', height);
}
final double width;
final double height;
}
/// The gaps a caller reserves around measured nodes.
///
/// [columnGap] separates adjacent ranks, [rowGap] separates nodes sharing a
/// rank, and [padding] is the outer margin included in [GraphLayout] bounds.
class GraphLayoutConfig {
GraphLayoutConfig({
required this.columnGap,
required this.rowGap,
this.padding = 0,
}) {
_requireFiniteNonNegative('columnGap', columnGap);
_requireFiniteNonNegative('rowGap', rowGap);
_requireFiniteNonNegative('padding', padding);
}
final double columnGap;
final double rowGap;
final double padding;
}
/// One placed node.
///
/// [key], [terminal] and [stageIndex] are the definition node's own identity,
/// copied unchanged. [x]/[y] are the measured rectangle's top-left corner in
/// graph space and [rank] is its 0-based topological column.
class GraphNodeBox {
const GraphNodeBox({
required this.key,
required this.terminal,
required this.stageIndex,
required this.rank,
required this.x,
required this.y,
required this.width,
required this.height,
});
final String key;
final bool terminal;
final int? stageIndex;
final int rank;
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 GraphNodeBox &&
other.key == key &&
other.terminal == terminal &&
other.stageIndex == stageIndex &&
other.rank == rank &&
other.x == x &&
other.y == y &&
other.width == width &&
other.height == height;
@override
int get hashCode =>
Object.hash(key, terminal, stageIndex, rank, x, y, width, height);
}
/// An immutable node layout: every placed box plus the total graph bounds.
///
/// [nodes] is ordered by rank first and definition order inside a rank; use
/// [ranks] or [nodeFor] for keyed lookup. [width] and [height] include the
/// caller's padding; every box's [right] and [bottom] stay inside them.
/// [ranks] exposes each definition key's 0-based rank; [rankCount] is the
/// number of columns (0 for an empty node set).
class GraphLayout {
GraphLayout({
required List<GraphNodeBox> nodes,
required this.width,
required this.height,
required this.rankCount,
required Map<String, int> ranks,
}) : nodes = List.unmodifiable(nodes),
ranks = Map.unmodifiable(ranks);
final List<GraphNodeBox> nodes;
final Map<String, int> ranks;
final double width;
final double height;
final int rankCount;
bool get isEmpty => nodes.isEmpty;
/// The placed box for [key], or null when the definition has no such node.
GraphNodeBox? nodeFor(String key) {
for (final node in nodes) {
if (node.key == key) return node;
}
return null;
}
}