feat(diagram-engine): add_graph — arrow-ordered layout as a container

The layout vocabulary's biggest gap, after D2/TALA's 'containers are
first-class at every layout stage': hierarchical zones and arrow-ordered
graphs could not mix. draw_graph did whole-page flowcharts, containers did
nesting, and 'an architecture zone whose contents follow the data flow' was
inexpressible.

add_graph is a macro operation: nodes+edges go through the existing layered
pass (graph.ts — cycle breaking, longest-path layering, barycentre crossing
reduction) which emits ordinary container/box/link operations, and the
resulting block participates in the outer flexbox like any node. dir col/row
transposes the flow. No new layout code — the coordinate work was always
generic; what was missing was the entry point below page level.

Synthetic layer ids are namespaced by the graph's own id (g1__layer0), fixing
the collision that previously made a second graph per page impossible.
graph.ts gains parent/prefix/rootId options; draw_graph keeps its behaviour
as the page-level case of the same code path.

4 new tests: embedding in a flexbox column, two graphs per page, dir
transposition, unknown-endpoint errors. 565 unit tests green, 8 engine e2e
green. Acceptance: three-zone architecture diagram (person/cloud zone,
arrow-ordered pipeline zone with decision branches and a bold arrow,
cylinder/queue storage zone, cross-zone links) verified in the real editor.
This commit is contained in:
dayuan.jiang
2026-08-09 22:08:43 +09:00
parent d9cdfba3e1
commit 78e31ebb2a
5 changed files with 222 additions and 2 deletions

View File

@@ -96,6 +96,12 @@ Use draw_graph when the diagram is boxes joined by arrows and the arrows define
them — a flowchart written as XML or as nested containers comes out as one column, which forces
every branch to jump over the step beside it.
Use restructure_diagram's add_graph when ONE ZONE of a nested diagram is arrow-ordered:
an architecture diagram where a zone's contents follow the data flow, a poster column with
a small flowchart in it. add_graph takes nodes+edges like draw_graph, lays them out inside
its container, and the container joins the outer layout like any node (dir: col flows
down, row flows right).
Use restructure_diagram when the diagram's meaning is in NESTING or in a fixed frame:
- Cloud architecture (AWS/Azure/GCP/Kubernetes): things inside things. Call search_stencils first.
- Swimlane and BPMN diagrams: add_pool with one lane per role, then add_box with lane and col.