feat: add ALTER PAGE ADD/DROP VARIABLE support (Phase 3)

Implement ADD/DROP variable operations for ALTER PAGE/SNIPPET,
completing Phase 3 of the page variables proposal. This enables
adding and removing page variables on existing pages without
requiring a full CREATE OR REPLACE.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

.claude/skills/mendix/alter-page.md

@@ -123,6 +123,22 @@ REPLACE footer1 WITH {
 
 Replaces the target widget with one or more new widgets. The new widgets use the same syntax as `CREATE PAGE`.
 
+### ADD Variables - Add a Page Variable
+
+```sql
+ADD Variables $showStockColumn: Boolean = 'true'
+```
+
+Adds a new page variable (`Forms$LocalVariable`) to the page/snippet. DataType can be `Boolean`, `String`, `Integer`, `Decimal`, `DateTime`, or an entity type. Default value is a Mendix expression in single quotes.
+
+### DROP Variables - Remove a Page Variable
+
+```sql
+DROP Variables $showStockColumn
+```
+
+Removes a page variable by name.
+
 ## Examples
 
 ### Change button text and style
@@ -143,6 +159,14 @@ ALTER PAGE MyModule.Customer_Edit {
 };
 ```
 
+### Add a page variable for column visibility
+
+```sql
+ALTER PAGE MyModule.ProductOverview {
+  ADD Variables $showStockColumn: Boolean = 'if (3 < 4) then true else false'
+};
+```
+
 ### Remove unused fields and update title
 
 ```sql

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -415,6 +415,8 @@ Modify an existing page or snippet's widget tree in-place without full `CREATE O
 | Drop widgets | `DROP WIDGET name1, name2` | Remove widgets by name |
 | Replace widget | `REPLACE widgetName WITH { widgets }` | Replace widget subtree |
 | Pluggable prop | `SET 'showLabel' = false ON cbStatus` | Quoted name for pluggable widgets |
+| Add variable | `ADD Variables $name: Type = 'expr'` | Add a page variable |
+| Drop variable | `DROP Variables $name` | Remove a page variable |
 
 **Supported SET properties:** Caption, Label, ButtonStyle, Class, Style, Editable, Visible, Name, Title (page-level), and quoted pluggable widget properties.
 

mdl-examples/doctype-tests/03-page-examples.mdl

@@ -2178,6 +2178,37 @@ CREATE PAGE PgTest.P036_ComboBox_Association
 
 -- ============================================================================================ --
 
+-- MARK: ALTER PAGE Variable Examples
+
+-- =============================================================================
+-- ALTER PAGE - ADD / DROP Page Variables
+-- =============================================================================
+--
+-- Page variables (Forms$LocalVariable) can be added to or removed from existing
+-- pages and snippets using ALTER PAGE / ALTER SNIPPET with ADD/DROP Variables.
+--
+
+-- Add a boolean page variable for controlling column visibility
+ALTER PAGE PgTest.P033b_DataGrid_ColumnProperties {
+  ADD Variables $showPriceColumn: Boolean = 'true';
+};
+
+-- Add a string variable with an escaped string default
+ALTER PAGE PgTest.P033b_DataGrid_ColumnProperties {
+  ADD Variables $filterMode: String = '''active''';
+};
+
+-- Drop a page variable by name
+ALTER PAGE PgTest.P033b_DataGrid_ColumnProperties {
+  DROP Variables $filterMode;
+};
+
+-- Multiple variable operations in a single ALTER statement
+ALTER PAGE PgTest.P033b_DataGrid_ColumnProperties {
+  ADD Variables $pageSize: Integer = '20';
+  DROP Variables $showPriceColumn;
+};
+
 -- MARK: Move Examples
 
 -- =============================================================================

mdl/ast/ast_alter_page.go

@@ -52,3 +52,17 @@ type ReplaceWidgetOp struct {
 }
 
 func (s *ReplaceWidgetOp) isAlterPageOperation() {}
+
+// AddVariableOp represents: ADD Variables $name: Type = 'default'
+type AddVariableOp struct {
+	Variable PageVariable
+}
+
+func (s *AddVariableOp) isAlterPageOperation() {}
+
+// DropVariableOp represents: DROP Variables $name
+type DropVariableOp struct {
+	VariableName string // without $ prefix
+}
+
+func (s *DropVariableOp) isAlterPageOperation() {}

mdl/executor/cmd_alter_page.go

@@ -89,6 +89,14 @@ func (e *Executor) execAlterPage(s *ast.AlterPageStmt) error {
 			if err := e.applyReplaceWidgetWith(rawData, o, modName, containerID, findWidget); err != nil {
 				return fmt.Errorf("REPLACE failed: %w", err)
 			}
+		case *ast.AddVariableOp:
+			if err := applyAddVariable(&rawData, o); err != nil {
+				return fmt.Errorf("ADD VARIABLE failed: %w", err)
+			}
+		case *ast.DropVariableOp:
+			if err := applyDropVariable(rawData, o); err != nil {
+				return fmt.Errorf("DROP VARIABLE failed: %w", err)
+			}
 		default:
 			return fmt.Errorf("unknown ALTER %s operation type: %T", containerType, op)
 		}
@@ -936,6 +944,85 @@ func extractEntityFromDataSource(wDoc bson.D) string {
 	return ""
 }
 
+// ============================================================================
+// ADD / DROP variable
+// ============================================================================
+
+// applyAddVariable adds a new LocalVariable to the raw BSON page/snippet.
+func applyAddVariable(rawData *bson.D, op *ast.AddVariableOp) error {
+	// Check for duplicate variable name
+	existingVars := dGetArrayElements(dGet(*rawData, "Variables"))
+	for _, ev := range existingVars {
+		if evDoc, ok := ev.(bson.D); ok {
+			if dGetString(evDoc, "Name") == op.Variable.Name {
+				return fmt.Errorf("variable $%s already exists", op.Variable.Name)
+			}
+		}
+	}
+
+	// Build VariableType BSON
+	varTypeID := mpr.GenerateID()
+	bsonTypeName := mdlTypeToBsonType(op.Variable.DataType)
+	varType := bson.D{
+		{Key: "$ID", Value: mpr.IDToBsonBinary(varTypeID)},
+		{Key: "$Type", Value: bsonTypeName},
+	}
+	if bsonTypeName == "DataTypes$ObjectType" {
+		varType = append(varType, bson.E{Key: "Entity", Value: op.Variable.DataType})
+	}
+
+	// Build LocalVariable BSON document
+	varID := mpr.GenerateID()
+	varDoc := bson.D{
+		{Key: "$ID", Value: mpr.IDToBsonBinary(varID)},
+		{Key: "$Type", Value: "Forms$LocalVariable"},
+		{Key: "DefaultValue", Value: op.Variable.DefaultValue},
+		{Key: "Name", Value: op.Variable.Name},
+		{Key: "VariableType", Value: varType},
+	}
+
+	// Append to existing Variables array, or create new field
+	existing := toBsonA(dGet(*rawData, "Variables"))
+	if existing != nil {
+		elements := dGetArrayElements(dGet(*rawData, "Variables"))
+		elements = append(elements, varDoc)
+		dSetArray(*rawData, "Variables", elements)
+	} else {
+		// Field doesn't exist — append to the document
+		*rawData = append(*rawData, bson.E{Key: "Variables", Value: bson.A{int32(3), varDoc}})
+	}
+
+	return nil
+}
+
+// applyDropVariable removes a LocalVariable from the raw BSON page/snippet.
+func applyDropVariable(rawData bson.D, op *ast.DropVariableOp) error {
+	elements := dGetArrayElements(dGet(rawData, "Variables"))
+	if elements == nil {
+		return fmt.Errorf("variable $%s not found", op.VariableName)
+	}
+
+	// Find and remove the variable
+	found := false
+	var kept []any
+	for _, elem := range elements {
+		if doc, ok := elem.(bson.D); ok {
+			if dGetString(doc, "Name") == op.VariableName {
+				found = true
+				continue
+			}
+		}
+		kept = append(kept, elem)
+	}
+
+	if !found {
+		return fmt.Errorf("variable $%s not found", op.VariableName)
+	}
+
+	dSetArray(rawData, "Variables", kept)
+	return nil
+}
+
 // ============================================================================
 // Widget BSON building
 // ============================================================================

mdl/grammar/MDLParser.g4

@@ -184,6 +184,8 @@ alterPageOperation
     | alterPageInsert SEMICOLON?
     | alterPageDrop SEMICOLON?
     | alterPageReplace SEMICOLON?
+    | alterPageAddVariable SEMICOLON?
+    | alterPageDropVariable SEMICOLON?
     ;
 
 alterPageSet
@@ -210,6 +212,14 @@ alterPageReplace
     : REPLACE identifierOrKeyword WITH LBRACE pageBodyV3 RBRACE
     ;
 
+alterPageAddVariable
+    : ADD VARIABLES_KW variableDeclaration    // ADD Variables $show: Boolean = 'true'
+    ;
+
+alterPageDropVariable
+    : DROP VARIABLES_KW VARIABLE              // DROP Variables $show
+    ;
+
 navigationClause
     : HOME (PAGE | MICROFLOW) qualifiedName (FOR qualifiedName)?
     | LOGIN PAGE qualifiedName