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.
4.8 KiB
P2b — deterministic pure node layout
What changed
New app-only, pure-Dart files. No existing file, server, web client, legacy
client, shell, main.dart, pubspec, other feature or platform source was edited.
| File | Lines | Responsibility |
|---|---|---|
lib/features/graph/layout/layout_models.dart |
127 | measured extents, gap config, immutable node box, layout + ranks |
lib/features/graph/layout/graph_ranks.dart |
191 | deterministic SCC ranks over the landed definition nodes/edges |
lib/features/graph/layout/graph_node_layout.dart |
142 | column/row placement, bounds, validation |
test/features/graph/layout/layout_fixtures.dart |
102 | shared definitions and measured extents |
test/features/graph/layout/graph_ranks_test.dart |
116 | linear/diamond/cycle/self-loop/disconnected/unknown/long-chain ranks |
test/features/graph/layout/graph_node_layout_test.dart |
224 | ordering, terminals, heterogeneous and expanded extents, bounds, determinism |
test/features/graph/layout/graph_layout_validation_test.dart |
96 | empty input, missing/extra measurements, duplicate keys, invalid sizes |
No layout widgets, painters, edge routing, styling or shell wiring were added.
Public API
GraphRanks assignGraphRanks(List<GraphNode> nodes, List<GraphEdge> edges);
GraphLayout layoutGraphNodes({
required List<GraphNode> nodes,
required List<GraphEdge> edges,
required Map<String, NodeExtent> extents,
required GraphLayoutConfig config,
});
NodeExtent is the caller's measured width/height after text layout.
GraphLayoutConfig takes columnGap, rowGap and an optional outer padding.
No node size, font, colour or device value is assumed in the library.
GraphLayout returns an unmodifiable nodes list of GraphNodeBox
(key, terminal, stageIndex, rank, x, y, width, height), an
unmodifiable ranks map, rankCount, and total width/height including
padding. Node keys, terminal flags and stage indices are copied from the
landed graphNodes identities unchanged.
Ranking behavior
Ranks are read from the definition supplied by the caller; the existing
graphNodes/graphEdges helpers remain the source of identities.
- Iterative Tarjan strongly connected components (no recursion; a 2000-stage chain is covered), then longest-path ranks over the condensation DAG.
- Every member of a cycle shares one rank, so cyclic routes cannot recurse or push members apart. Self loops are internal supervision and add no rank.
- Disconnected stages and disconnected terminals stay at rank 0.
- Edges whose source or target is not a node are ignored. An unknown or empty target never creates a node or a rank.
- Ranking is linear in nodes plus edges and stable for repeated input.
Placement behavior
- One column per rank; nodes keep definition order inside a rank.
- A column is as wide as its widest measured node; columns are separated by
columnGapand top-aligned. - Nodes are centred in their column and stacked with exactly
rowGapbetween measured boxes (centres are compared in the heterogeneous test). - Supplied widths/heights are placed verbatim, so expanded text is never clipped to a fixed box; growing the extents grows the total bounds.
- Bounds include every box: tests assert
right <= widthandbottom <= heightfor every fixture. - The result is immutable and identical for identical input.
Measurements are required for every node; a missing key throws
ArgumentError rather than inventing a default size. Extra measurements are
ignored because they cannot become nodes. Duplicate/empty node keys, negative
or non-finite gaps and extents are rejected.
Checks actually run
flutter pub get
dart format lib/features/graph/layout test/features/graph/layout
flutter test test/features/graph/layout # 21 passed
flutter analyze # No issues found!
flutter test # 173 passed
git diff --check # clean
Tests cover linear, diamond, cycle, self-loop, disconnected, terminals, unknown/empty targets, heterogeneous extents, 2.6x expanded text, determinism, bounds and invalid input.
Honest limits
- Nodes only. Edge routing, ports, labels, lanes, hit testing, selection highlighting, painting and native controls are separate later items.
- Not rendered. A pure nonvisual slice has no browser behavior to capture; no screenshot or browser check applies.
- 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.