Merge pull request #333 from hjotha/submit/microflow-download-file-statement

feat: support microflow download file statement

Author: ako

.claude/skills/mendix/write-microflows.md

@@ -824,6 +824,17 @@ rest call delete 'https://api.example.com/items/{1}' with (
 
 **REST CALL supports full error handling** (`on error continue`, `on error rollback`, custom error handlers).
 
+## File Downloads
+
+Use `download file` to stream a `System.FileDocument` from a microflow. Add
+`show in browser` when the action should open the file inline instead of forcing
+a download.
+
+```mdl
+download file $GeneratedReport show in browser;
+download file $GeneratedExport;
+```
+
 ## Error Handling
 
 MDL supports error handling for activities that may fail (microflow calls, commits, external service calls, etc.).

cmd/mxcli/lsp_completions_gen.go

@@ -225,6 +225,7 @@ authentication basic, session
 | Call nanoflow | `$Result = call nanoflow Module.Name (Param = $value);` | |
 | Show page | `show page Module.PageName ($Param = $value);` | Also accepts `(Param: $value)` |
 | Close page | `close page;` | |
+| Download file | `download file $FileDocument [show in browser];` | Streams a `System.FileDocument` |
 | Validation | `validation feedback $entity/attribute message 'message';` | Requires attribute path + MESSAGE |
 | Log | `log info\|warning\|error [node 'name'] 'message';` | |
 | Position | `@position(x, y)` | Canvas position (before activity) |

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -0,0 +1,49 @@
+# Microflow Download File Statement
+
+Status: Draft
+
+## Summary
+
+Add MDL syntax for Mendix `Microflows$DownloadFileAction`:
+
+```mdl
+download file $GeneratedReport;
+download file $GeneratedReport show in browser;
+```
+
+The feature is intentionally small: it exposes an existing Studio Pro microflow
+activity without adding new semantics.
+
+## Motivation
+
+Projects that already contain download-file actions should survive
+describe/exec/describe without losing the activity or falling back to an
+unsupported-action comment. The statement also gives users a straightforward way
+to author file downloads when the file document variable already exists.
+
+## Syntax
+
+```antlr
+downloadFileStatement
+    : DOWNLOAD FILE_KW VARIABLE (SHOW IN BROWSER)? onErrorClause? SEMICOLON
+    ;
+```
+
+Examples:
+
+```mdl
+download file $GeneratedExport;
+download file $GeneratedReport show in browser on error rollback;
+```
+
+## Semantics
+
+- The operand must be a variable containing a `System.FileDocument`.
+- `show in browser` maps to Studio Pro's `ShowInBrowser` flag.
+- Error handling follows the normal microflow action `on error ...` forms.
+
+## Tests And Examples
+
+- Parser/visitor coverage for both normal and `show in browser` forms.
+- Builder/writer coverage for `DownloadFileAction`.
+- Example script: `mdl-examples/doctype-tests/download_file.test.mdl`.

docs/11-proposals/PROPOSAL_microflow_download_file_statement.md

@@ -43,6 +43,7 @@ BSON schema Registry ◄──── multi-version Support
 |----------|--------|---------|------------|
 | [MDL Syntax Improvements v1](PROPOSAL_mdl_syntax_improvements.md) | Draft | Go-style assignment, C-style braces, fluent list APIs | — |
 | [MDL Syntax Improvements v2](PROPOSAL_mdl_syntax_improvements_v2.md) | Proposed | Consolidated v2: unified variable declaration, C-style braces, fluent list ops | Syntax Improvements v1 |
+| [Microflow Download File Statement](PROPOSAL_microflow_download_file_statement.md) | Draft | `download file $FileDocument [show in browser]` for `DownloadFileAction` round-trip and authoring | — |
 | [Page Syntax V2](PROPOSAL_page_syntax_v2.md) | Superseded | Page/widget syntax with `{}` blocks and `->` binding. Superseded by V3 (archived) | — |
 | [Page Styling Support](page-styling-support.md) | Partial | CSS classes, inline styles, dynamic classes, design properties. Phase 1 (Class/Style) done | — |
 | [Page Composition](proposal_page_composition.md) | Proposed | Fragment definitions and ALTER PAGE for partial page editing | Page Syntax V2, Page Styling |

docs/11-proposals/README.md

@@ -0,0 +1,19 @@
+create microflow SampleFiles.ACT_DownloadReport (
+  $GeneratedReport: System.FileDocument
+)
+returns Void
+begin
+  download file $GeneratedReport show in browser;
+  return;
+end;
+/
+
+create microflow SampleFiles.ACT_DownloadExport (
+  $GeneratedExport: System.FileDocument
+)
+returns Void
+begin
+  download file $GeneratedExport;
+  return;
+end;
+/

mdl-examples/doctype-tests/download_file.test.mdl

@@ -570,6 +570,16 @@ type ShowMessageStmt struct {
 
 func (s *ShowMessageStmt) isMicroflowStatement() {}
 
+// DownloadFileStmt represents: DOWNLOAD FILE $FileDocument [SHOW IN BROWSER]
+type DownloadFileStmt struct {
+	FileDocument  string               // File document variable without $ prefix
+	ShowInBrowser bool                 // Whether the file opens in the browser
+	ErrorHandling *ErrorHandlingClause // Optional ON ERROR clause
+	Annotations   *ActivityAnnotations // Optional @position, @caption, @color, @annotation
+}
+
+func (s *DownloadFileStmt) isMicroflowStatement() {}
+
 // ValidationFeedbackStmt represents: VALIDATION FEEDBACK $Var/Attr MESSAGE 'message' OBJECTS [$Var1, $Var2];
 type ValidationFeedbackStmt struct {
 	AttributePath *AttributePathExpr   // The attribute to associate with the feedback

mdl/ast/ast_microflow.go

@@ -71,6 +71,8 @@ func getStatementAnnotations(stmt ast.MicroflowStatement) *ast.ActivityAnnotatio
 		return s.Annotations
 	case *ast.ShowMessageStmt:
 		return s.Annotations
+	case *ast.DownloadFileStmt:
+		return s.Annotations
 	case *ast.ValidationFeedbackStmt:
 		return s.Annotations
 	case *ast.RestCallStmt:

mdl/executor/cmd_microflows_builder_annotations.go

@@ -476,6 +476,35 @@ func (fb *flowBuilder) addShowMessageAction(s *ast.ShowMessageStmt) model.ID {
 	return activity.ID
 }
 
+// addDownloadFileAction creates a DOWNLOAD FILE statement.
+func (fb *flowBuilder) addDownloadFileAction(s *ast.DownloadFileStmt) model.ID {
+	action := &microflows.DownloadFileAction{
+		BaseElement:       model.BaseElement{ID: model.ID(types.GenerateID())},
+		FileDocument:      s.FileDocument,
+		ShowInBrowser:     s.ShowInBrowser,
+		ErrorHandlingType: microflows.ErrorHandlingTypeRollback,
+	}
+	if s.ErrorHandling != nil {
+		action.ErrorHandlingType = convertErrorHandlingType(s.ErrorHandling)
+	}
+
+	activity := &microflows.ActionActivity{
+		BaseActivity: microflows.BaseActivity{
+			BaseMicroflowObject: microflows.BaseMicroflowObject{
+				BaseElement: model.BaseElement{ID: model.ID(types.GenerateID())},
+				Position:    model.Point{X: fb.posX, Y: fb.posY},
+				Size:        model.Size{Width: ActivityWidth, Height: ActivityHeight},
+			},
+			AutoGenerateCaption: true,
+		},
+		Action: action,
+	}
+
+	fb.objects = append(fb.objects, activity)
+	fb.posX += fb.spacing
+	return activity.ID
+}
+
 // addClosePageAction creates a CLOSE PAGE statement.
 func (fb *flowBuilder) addClosePageAction(s *ast.ClosePageStmt) model.ID {
 	numPages := s.NumberOfPages

mdl/executor/cmd_microflows_builder_calls.go

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+)
+
+func TestBuildFlowGraph_DownloadFileCreatesRealAction(t *testing.T) {
+	fb := &flowBuilder{
+		posX:         100,
+		posY:         100,
+		spacing:      HorizontalSpacing,
+		varTypes:     map[string]string{"GeneratedReport": "System.FileDocument"},
+		declaredVars: map[string]string{"GeneratedReport": "System.FileDocument"},
+	}
+
+	fb.buildFlowGraph([]ast.MicroflowStatement{
+		&ast.DownloadFileStmt{
+			FileDocument:  "GeneratedReport",
+			ShowInBrowser: true,
+			ErrorHandling: &ast.ErrorHandlingClause{Type: ast.ErrorHandlingContinue},
+		},
+	}, nil)
+
+	var action *microflows.DownloadFileAction
+	for _, obj := range fb.objects {
+		activity, ok := obj.(*microflows.ActionActivity)
+		if !ok {
+			continue
+		}
+		if dl, ok := activity.Action.(*microflows.DownloadFileAction); ok {
+			action = dl
+			break
+		}
+	}
+	if action == nil {
+		t.Fatal("expected DownloadFileAction")
+	}
+	if action.FileDocument != "GeneratedReport" {
+		t.Fatalf("FileDocument = %q, want GeneratedReport", action.FileDocument)
+	}
+	if !action.ShowInBrowser {
+		t.Fatal("ShowInBrowser = false, want true")
+	}
+	if action.ErrorHandlingType != microflows.ErrorHandlingTypeContinue {
+		t.Fatalf("ErrorHandlingType = %q, want Continue", action.ErrorHandlingType)
+	}
+}