Skip to content

Commit 643271e

Browse files
authored
Merge pull request mendixlabs#1155 from tgolembiewski/feature/1154-microflow-auto-layout
fix: lay out microflows written without @position so they can be read
2 parents 43a29ce + 5543744 commit 643271e

26 files changed

Lines changed: 1494 additions & 53 deletions

‎.claude/skills/fix-issue/findings/mdl-executor.jsonl‎

Lines changed: 1 addition & 0 deletions
Large diffs are not rendered by default.

‎.claude/skills/mendix/write-microflows/reference/control-flow.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -307,6 +307,7 @@ commit $Product;
307307
- `@annotation` before activity-binding metadata such as `@position`, `@caption`, `@color`, `@excluded`, or `@anchor` stays free-floating when later metadata binds the following activity
308308
- `@annotation` at the end (no following activity) creates a free-floating note
309309
- Escape single quotes by doubling: `@annotation 'Don''t forget'`
310+
- **Leave `@position` out unless you are reproducing a hand-made diagram.** Without it the builder lays the flow out itself: the main line wraps onto rows past two canvas widths, a guard's branch drops into the lane below while the main line carries on above it, and a `case` of four or more branches leaves the decision in three groups so its lines do not cross. A statement with `@position` is never moved and is not measured against what is placed around it, so a few hand-placed statements in an otherwise automatic flow are what produces overlaps (mendixlabs/mxcli#1154)
310311
- `@position` always appears in DESCRIBE output; `@caption` only when custom; `@color` only when not Default
311312
- DESCRIBE MICROFLOW shows `@` annotations before their activities
312313
- `@start(x, y)` positions the **start event** and goes on the first statement, because the start has no statement of its own. Omit it and the start is derived — one spacing unit (160) left of the first activity, on its centre line — and a rewrite re-derives it so the start follows the activities when they move. A start that is not at the derived spot was placed by hand (in Studio Pro or with `@start`): it survives a rewrite that does not mention it, and DESCRIBE emits `@start` for it. An explicit `@start` overrides both (#951)

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
66

77
## [Unreleased]
88

9+
### Changed
10+
11+
- **Microflows written without `@position` are laid out to be read, not just to be valid** (mendixlabs/mxcli#1154). Geometry and connection sides only: no MDL syntax changes, a statement carrying `@position` is never moved, and `describe` → `exec` still reports `Unchanged microflow`. Measured on a generated app of 41 microflows, none with an `@position`: the widest flow went from 6930×160 px on one row to 3220 px, with 0 overlapping elements and `mx check` at 0 errors before and after.
12+
13+
- **A long main line wraps onto rows.** Past 2880 px (two Studio Pro canvases) the next statement starts a new row under everything the current row occupies — branch lanes, loop boxes and notes included, measured after they are built rather than estimated. The line joining two rows leaves the bottom of the last element and arrives on top of the first, so it runs through the band between the rows instead of back across the activities. A tail short enough to finish within two more activities stays on its row rather than becoming a stub underneath.
14+
- **The main line no longer waits for a guard's branch.** `if … then …; return; end if` draws its branch in the lane below and ends it there, yet the next element used to be placed past the branch's far end: 370 px from the split, against 40 px between any two activities. It now stands in the column the branch starts in, and only an element that reaches down into that lane — another decision, a loop, an activity with an error handler — waits for the lane to clear. A merge stands one ordinary gap after its branch (was 120 px), a branch ending in `return` is measured with the end event it draws, and a loop box keeps the same 40 px gap from its neighbours as an activity.
15+
- **An enumeration split of four or more cases draws its lines in three groups** — the upper third from the split's top corner, the middle from its right, the lower from its bottom, every one arriving on the left of its activity, mirrored on the merge. The anchor pair on these flows is where the `case` order is stored, and past the third case the table behind it used sides no drawing would choose: case 4 left the split's left corner, cases 5–8 arrived on top of their activity. `describe` now reads the order as side, then position on the canvas; a model written with one pair per case reads exactly as before, and a split of up to three cases is unchanged.
16+
- **A note sits above its element, not inside it.** Notes were offset from the element's centre, which is inside any loop box; they are now placed above its top edge, and the connector runs from the bottom of the note to the top of the element instead of top to top.
17+
918
### Fixed
1019

1120
- **A page's image-collection reference passed `mxcli check --references` and failed the build** (mendixlabs/mxcli#1149) — `staticimage imgAll (Image: 'Atlas_UI_Resources.Atlas_Icons.checkbox_checked')` in a Selection helper's custom state checked clean, exec'd cleanly and then came back as `[error] [CE1613] "The selected image … no longer exists."`, once per state. The report asks for syntax, but the syntax landed with #1057 — describe emits the three `staticimage` lines and re-running the description reports `Unchanged page`, measured on a blank 11.14.0 project. What was missing is that nothing resolved the name #1057 had made writable.

‎cmd/mxcli/syntax/features_microflow.go‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -500,6 +500,15 @@ func init() {
500500
"pixel offset from its end of the line. (0, 0) at both ends is straight.\n" +
501501
"@position on a split belongs to the SPLIT, so its end-if join has its own\n" +
502502
"annotation. Container Size is still computed, not authorable.\n\n" +
503+
"WITHOUT @position the builder places everything. The main line runs left to\n" +
504+
"right and wraps onto a new row past 2880px; the line joining two rows leaves\n" +
505+
"the bottom of one and arrives on top of the next. A guard (if … return; end\n" +
506+
"if) drops its branch into the lane below and the main line carries straight\n" +
507+
"on over it. A CASE of four or more branches leaves the split in three groups\n" +
508+
"— top, right, bottom — so its lines do not cross. A statement that carries\n" +
509+
"@position is never moved, and starts the row for what follows it. Prefer no\n" +
510+
"@position at all to a few: hand-placed statements are not measured against\n" +
511+
"what the builder puts around them. (#1154)\n\n" +
503512
"@start and @merge position the two nodes that have no statement of their\n" +
504513
"own, so each is written on the statement it belongs to. Omit @start and the\n" +
505514
"start is placed one spacing unit left of the first activity, on its centre\n" +

‎docs-site/src/language/microflow-structure.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,15 @@ Set the canvas position of the next activity:
138138
$Order = CREATE Sales.Order (Status = 'New');
139139
```
140140

141+
Positions are optional. A microflow written without them is laid out by mxcli: the
142+
main line runs left to right and wraps onto a new row once it passes two canvas
143+
widths (2880 px); a guard — `if … then …; return; end if` — drops its branch into the
144+
lane below while the main line carries on above it; and a `case` of four or more
145+
branches leaves the decision in three groups (top, right, bottom) so its lines do not
146+
cross. A statement that carries `@position` is never moved, and becomes the start of
147+
the row for the statements after it — so either place everything or nothing: a few
148+
hand-placed statements are not measured against what is laid out around them.
149+
141150
### Start event
142151

143152
The start event has no statement of its own, so `@start` goes on the **first**
Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
-- Auto-layout of a microflow written with no @position: long main lines, guards
2+
-- and wide enumeration splits.
3+
--
4+
-- Measured on a generated app of 41 microflows (Mendix 11.12.1, mxcli v0.23.0), none
5+
-- of them carrying an @position: nothing overlapped, and the widest flow was
6+
-- 6930x160 px - four screens of sideways scrolling. Every guard left 370px of bare
7+
-- main line above its own branch (40px between any two activities), a merge stood
8+
-- 120px after its branch, and a 7-case split sent its fourth case out of the split's
9+
-- LEFT corner and its fifth onwards onto the TOP of their activities, because the
10+
-- anchor pair was storing the case order.
11+
--
12+
-- Open the three flows in Studio Pro after exec:
13+
-- MF_LayoutLong wraps onto rows; the joining line runs between the rows
14+
-- MF_LayoutGuards each activity after a guard stands in the branch's column
15+
-- MF_LayoutCases case lines leave the split top / right / bottom, 2-3-2
16+
--
17+
-- mendixlabs/mxcli#1154
18+
19+
CREATE ENUMERATION MyFirstModule.LayoutStatus (
20+
NewOrder 'New', Confirmed 'Confirmed', InProgress 'In progress', Shipped 'Shipped',
21+
Delivered 'Delivered', Invoiced 'Invoiced'
22+
);
23+
24+
CREATE MICROFLOW MyFirstModule.MF_LayoutLong ()
25+
BEGIN
26+
LOG INFO 'step 1';
27+
LOG INFO 'step 2';
28+
LOG INFO 'step 3';
29+
LOG INFO 'step 4';
30+
LOG INFO 'step 5';
31+
LOG INFO 'step 6';
32+
LOG INFO 'step 7';
33+
LOG INFO 'step 8';
34+
LOG INFO 'step 9';
35+
LOG INFO 'step 10';
36+
LOG INFO 'step 11';
37+
LOG INFO 'step 12';
38+
LOG INFO 'step 13';
39+
LOG INFO 'step 14';
40+
LOG INFO 'step 15';
41+
LOG INFO 'step 16';
42+
LOG INFO 'step 17';
43+
LOG INFO 'step 18';
44+
LOG INFO 'step 19';
45+
LOG INFO 'step 20';
46+
LOG INFO 'step 21';
47+
LOG INFO 'step 22';
48+
LOG INFO 'step 23';
49+
LOG INFO 'step 24';
50+
LOG INFO 'step 25';
51+
LOG INFO 'step 26';
52+
LOG INFO 'step 27';
53+
LOG INFO 'step 28';
54+
LOG INFO 'step 29';
55+
LOG INFO 'step 30';
56+
LOG INFO 'step 31';
57+
LOG INFO 'step 32';
58+
LOG INFO 'step 33';
59+
LOG INFO 'step 34';
60+
LOG INFO 'step 35';
61+
LOG INFO 'step 36';
62+
LOG INFO 'step 37';
63+
LOG INFO 'step 38';
64+
LOG INFO 'step 39';
65+
LOG INFO 'step 40';
66+
END;
67+
/
68+
69+
CREATE MICROFLOW MyFirstModule.MF_LayoutGuards ($Amount: Integer, $Limit: Integer)
70+
RETURNS Boolean AS $IsAccepted
71+
BEGIN
72+
IF $Amount = 0 THEN
73+
LOG WARNING 'nothing to place';
74+
RETURN false;
75+
END IF;
76+
LOG INFO 'amount present';
77+
IF $Amount > $Limit THEN
78+
LOG WARNING 'over the limit';
79+
RETURN false;
80+
END IF;
81+
IF $Limit < 0 THEN
82+
LOG WARNING 'no credit at all';
83+
RETURN false;
84+
END IF;
85+
LOG INFO 'accepted';
86+
RETURN true;
87+
END;
88+
/
89+
90+
CREATE MICROFLOW MyFirstModule.MF_LayoutCases ($Status: MyFirstModule.LayoutStatus)
91+
RETURNS String AS $Next
92+
BEGIN
93+
DECLARE $Next String = '';
94+
CASE $Status
95+
WHEN NewOrder THEN
96+
SET $Next = 'Confirmed';
97+
WHEN Confirmed THEN
98+
SET $Next = 'InProgress';
99+
WHEN InProgress THEN
100+
SET $Next = 'Shipped';
101+
WHEN Shipped THEN
102+
SET $Next = 'Delivered';
103+
WHEN Delivered THEN
104+
SET $Next = 'Invoiced';
105+
WHEN Invoiced THEN
106+
SET $Next = 'Invoiced';
107+
WHEN (empty) THEN
108+
SET $Next = 'NewOrder';
109+
END CASE;
110+
RETURN $Next;
111+
END;
112+
/

‎mdl/backend/modelsdk/microflow_write.go‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -421,7 +421,10 @@ func annotationFlowToGen(af *microflows.AnnotationFlow, major int) element.Eleme
421421
g.SetID(element.ID(af.ID))
422422
g.SetOriginID(element.ID(af.OriginID))
423423
g.SetDestinationID(element.ID(af.DestinationID))
424-
g.SetOriginConnectionIndex(0)
424+
// A note sits ABOVE the element it documents, so its line leaves the note's
425+
// bottom edge and enters the element's top. Both indexes were 0 (top), which
426+
// drew the line out of the top of the note and back down around it.
427+
g.SetOriginConnectionIndex(2)
425428
g.SetDestinationConnectionIndex(0)
426429
if major <= 9 {
427430
g.SetOriginBezierVector("0;0")

‎mdl/executor/bugfix_regression_test.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ func TestAddLoopStatement_PreservesAnnotatedPosition(t *testing.T) {
9797
if loop.Position.X != 350 || loop.Position.Y != 200 {
9898
t.Fatalf("got loop position (%d, %d), want (350, 200)", loop.Position.X, loop.Position.Y)
9999
}
100-
wantNextX := 350 + loop.Size.Width/2 + HorizontalSpacing
100+
wantNextX := 350 + loop.Size.Width/2 + ActivityWidth/2 + (HorizontalSpacing - ActivityWidth) // the next activity sits one activity-gap past the box
101101
if fb.posX != wantNextX {
102102
t.Fatalf("got next posX %d, want %d", fb.posX, wantNextX)
103103
}
@@ -136,7 +136,7 @@ func TestAddWhileStatement_PreservesAnnotatedPosition(t *testing.T) {
136136
if loop.Position.X != 420 || loop.Position.Y != 180 {
137137
t.Fatalf("got while position (%d, %d), want (420, 180)", loop.Position.X, loop.Position.Y)
138138
}
139-
wantNextX := 420 + loop.Size.Width/2 + HorizontalSpacing
139+
wantNextX := 420 + loop.Size.Width/2 + ActivityWidth/2 + (HorizontalSpacing - ActivityWidth) // the next activity sits one activity-gap past the box
140140
if fb.posX != wantNextX {
141141
t.Fatalf("got next posX %d, want %d", fb.posX, wantNextX)
142142
}

‎mdl/executor/cmd_microflows_build.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -407,6 +407,7 @@ func buildMicroflowFromStmt(ctx *ExecContext, s *ast.CreateMicroflowStmt, opts b
407407
varTypes: varTypes,
408408
declaredVars: declaredVars,
409409
measurer: &layoutMeasurer{varTypes: varTypes},
410+
allowWrap: true,
410411
backend: ctx.Backend,
411412
hierarchy: hierarchy,
412413
restServices: restServices,
@@ -685,6 +686,7 @@ func buildNanoflowFromStmt(ctx *ExecContext, s *ast.CreateNanoflowStmt, opts bui
685686
varTypes: varTypes,
686687
declaredVars: declaredVars,
687688
measurer: &layoutMeasurer{varTypes: varTypes},
689+
allowWrap: true,
688690
backend: ctx.Backend,
689691
hierarchy: hierarchy,
690692
restServices: restServices,

‎mdl/executor/cmd_microflows_builder.go‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,16 @@ type flowBuilder struct {
113113
// pendingJoin is the `join` addStatement just saw, waiting for the enclosing
114114
// body loop to say which activity the path had reached.
115115
pendingJoin *ast.JoinStmt
116+
// lowerLane is how far right the lane under each main line (keyed by the line's
117+
// y) is occupied by a guard's branch. See layout_lanes.go.
118+
lowerLane map[int]int
119+
// allowWrap turns on row wrapping for this builder: the main line breaks onto a
120+
// new row past MaxRowWidth instead of running off the canvas (layout_rows.go).
121+
// Only the builders that lay out a whole microflow set it; a loop body builds in
122+
// its own coordinate space inside a box that is sized to fit, so wrapping there
123+
// would fight the box rather than help the reader.
124+
allowWrap bool
125+
row rowTracker
116126
}
117127

118128
type flowBuilderVariableState struct {

0 commit comments

Comments
 (0)