Merge pull request #6 from ETH-PEACH-Lab/feat/add-set-text-and-text-dot-accessing

feat: add setText method and examples for text positioning in data st…

Author: Yang-Emily

docs/data-structures/array.md

@@ -43,6 +43,9 @@ Arrays support the following properties:
 
 Arrays support these methods for manipulation:
 
+### Text Positioning Methods
+- `setText(text, position)` - Set or remove text at specific positions (`"above"`, `"below"`, `"left"`, `"right"`)
+
 ### Single Element Methods
 - `setValue(index, value)` - Set value at specific index
 - `setColor(index, color)` - Set color at specific index  
@@ -147,6 +150,38 @@ show scores
 `}
 </SideBySide>
 
+### Dynamic Text with setText
+
+<SideBySide 
+  language="merlin"
+  bordered={true}
+  diagramWidth={400}
+  diagramHeight={300}
+  overrideSize={true}
+>
+{`
+array arr = {
+    value: [1, 2, 3, 4]
+}
+
+page
+show arr
+
+page
+arr.setText("Array Elements", "above")
+arr.setText("Index: 0, 1, 2, 3", "below")
+
+page
+arr.setText("Modified Array", "above")
+arr.above.setFontWeight("bold")
+arr.below.setColor("gray")
+
+page
+arr.setText(null, "below")  // remove bottom text
+arr.setText("Size: 4", "right")
+`}
+</SideBySide>
+
 ## Use Cases
 
 Arrays are ideal for:

docs/data-structures/graph.md

@@ -48,6 +48,9 @@ Graphs support the following properties:
 
 Graphs support these methods for manipulation:
 
+### Text Positioning Methods
+- `setText(text, position)` - Set or remove text at specific positions (`"above"`, `"below"`, `"left"`, `"right"`)
+
 ### Node Methods
 - `addNode(name, value?)` - Add new node with optional value
 - `removeNode(name)` - Remove node and its edges

docs/data-structures/linkedlist.md

@@ -45,6 +45,9 @@ LinkedLists support the following properties:
 
 LinkedLists support these methods for manipulation:
 
+### Text Positioning Methods
+- `setText(text, position)` - Set or remove text at specific positions (`"above"`, `"below"`, `"left"`, `"right"`)
+
 ### Node Methods
 - `addNode(name, value?)` - Add new node with optional value
 - `insertNode(index | id, name, value?)` - Insert node at specific position or after node ID with optional value

docs/data-structures/matrix.md

@@ -43,6 +43,9 @@ Matrices support the following properties:
 
 Matrices support these methods for manipulation:
 
+### Text Positioning Methods
+- `setText(text, position)` - Set or remove text at specific positions (`"above"`, `"below"`, `"left"`, `"right"`)
+
 ### Single Element Methods
 - `setValue(row, col, value)` - Set value at specific position
 - `setColor(row, col, color)` - Set color at specific position
@@ -171,6 +174,38 @@ show myMatrix
 `}
 </SideBySide>
 
+### Dynamic Text with setText
+
+<SideBySide 
+  language="merlin"
+  bordered={true}
+  diagramWidth={400}
+  diagramHeight={350}
+  overrideSize={true}
+>
+{`
+matrix data = {
+    value: [[1, 2], [3, 4]]
+}
+
+page
+show data
+
+page
+data.setText("Matrix Title", "above")
+data.setText("Row Labels", "left")
+
+page
+data.setText("Updated Title", "above")
+data.above.setFontSize(18)
+data.above.setColor("blue")
+
+page
+data.setText(null, "left")  // remove left text
+data.setText("Column Info", "below")
+`}
+</SideBySide>
+
 ## Use Cases
 
 Matrices are ideal for:

docs/data-structures/stack.md

@@ -43,6 +43,9 @@ Stacks support the following properties:
 
 Stacks support these methods for manipulation:
 
+### Text Positioning Methods
+- `setText(text, position)` - Set or remove text at specific positions (`"above"`, `"below"`, `"left"`, `"right"`)
+
 ### Single Element Methods
 - `setValue(index, value)` - Set value at specific position
 - `setColor(index, color)` - Set color at specific position  

docs/data-structures/text.md

@@ -60,7 +60,13 @@ Text elements support the following properties:
 
 Text elements support these methods for manipulation:
 
+:::info
+Text objects do not support the `setText()` method since they are text themselves. Use `setValue()`, `setFontSize()`, and other text-specific methods instead.
+:::
+
 ### Single Property Methods
+- `setValue(value)` - Set text content for all lines  
+- `setValue(line, value)` - Set text content for specific line
 - `setFontSize(value)` - Set font size for all text
 - `setFontSize(line, size)` - Set font size for specific line
 - `setColor(line, color)` - Set color for specific line
@@ -75,6 +81,7 @@ Text elements support these methods for manipulation:
 - `setHeight(height)` - Set text box height
 
 ### Multiple Element Methods
+- `setValues([...])` - Set text content for multiple lines
 - `setFontSizes([...])` - Set font sizes for multiple lines
 - `setColors([...])` - Set colors for multiple lines
 - `setFontWeights([...])` - Set font weights for multiple lines
@@ -152,6 +159,35 @@ status.setFontWeight("bold")
 `}
 </SideBySide>
 
+### Multiple Lines with setValues
+
+<SideBySide 
+  language="merlin"
+  bordered={true}
+  diagramWidth={400}
+  diagramHeight={300}
+  overrideSize={true}
+>
+{`
+text progress = {
+    value: ["Step 1: Initialize", "Step 2: Process", "Step 3: Complete"]
+    fontSize: 14
+    color: ["gray", "gray", "gray"]
+}
+
+page
+show progress
+
+page
+progress.setValues(["Step 1: Initialize ✓", "Step 2: Process...", "Step 3: Complete"])
+progress.setColors(["green", "orange", "gray"])
+
+page
+progress.setValues(["Step 1: Initialize ✓", "Step 2: Process ✓", "Step 3: Complete ✓"])
+progress.setColors(["green", "green", "green"])
+`}
+</SideBySide>
+
 ### Text as Data Labels
 
 <SideBySide 

docs/data-structures/tree.md

@@ -46,6 +46,9 @@ Trees support the following properties:
 
 Trees support these methods for manipulation:
 
+### Text Positioning Methods
+- `setText(text, position)` - Set or remove text at specific positions (`"above"`, `"below"`, `"left"`, `"right"`)
+
 ### Node Methods
 - `addNode(name, value?)` - Add new node with optional value
 - `removeNode(name)` - Remove node and its subtree

docs/methods.md

@@ -88,6 +88,30 @@ matrix.setValue(1, 2, "newValue")
 
 ---
 
+### `setValue(value)`
+Sets the text content for all lines.
+
+**Syntax:**
+```merlin
+text.setValue("newText")
+```
+
+**Supported by:** Text
+
+---
+
+### `setValue(line, value)`
+Sets the text content for a specific line.
+
+**Syntax:**
+```merlin
+text.setValue(0, "newText")  // first line
+```
+
+**Supported by:** Text
+
+---
+
 ### `setColor(index, color)`
 Sets the color at a specific index.
 
@@ -192,7 +216,7 @@ obj.setValues([1, 2, 3])
 obj.setValues([_, 2, _])  // only change middle value
 ```
 
-**Supported by:** Array, Stack, LinkedList, Graph, Tree
+**Supported by:** Array, Stack, LinkedList, Graph, Tree, Text
 
 ---
 
@@ -271,6 +295,44 @@ graph.setHidden([true, false, true])
 
 ---
 
+## Text Positioning Methods
+
+### `setText(text, position)`
+Sets or removes text at a specific position around a data structure.
+
+**Syntax:**
+```merlin
+obj.setText("text", "above")
+obj.setText("text", "below")
+obj.setText("text", "left")
+obj.setText("text", "right")
+obj.setText(null, "above")  // remove text
+```
+
+**Parameters:**
+- `text`: String value to set, or `null` to remove text
+- `position`: String literal indicating placement - `"above"`, `"below"`, `"left"`, or `"right"`
+
+**Behavior:**
+- Creates a new text component if none exists at the specified position
+- Updates existing text component if one exists at the position
+- Removes text component when `text` is `null`
+- Automatically handles text object lifecycle (creation/deletion)
+
+**Chained Method Access:**
+Access methods of linked text objects through position chaining:
+```merlin
+// Access text object methods through the main object
+obj.above.setFontSize(16)
+obj.below.setColor("#ff0000")
+obj.left.setValue("New Text")
+obj.right.setFontWeight("bold")
+```
+
+**Supported by:** Array, Matrix, Graph, Tree, Stack, LinkedList (all non-text structures)
+
+---
+
 ## Add/Insert Methods
 
 ### `addValue(value)`
@@ -737,12 +799,12 @@ text.setAligns(["left", "center", "right"])
 
 ## Method Compatibility
 
-| Data Structure | setValue | setColor | setArrow | add/insert | remove | Special Methods |
-|---------------|----------|----------|----------|------------|--------|----------------|
-| Array | ✓ (index) | ✓ (index) | ✓ (index) | ✓ | ✓ | - |
-| Matrix | ✓ (2D) | ✓ (2D) | ✓ (2D) | - | - | addRow, addColumn, addBorder |
-| Graph | ✓ (index/id) | ✓ (index/id) | ✓ (index/id) | ✓ | ✓ | setHidden (index/id), addEdge, setEdges |
-| Tree | ✓ (index/id) | ✓ (index/id) | ✓ (index/id) | ✓ | ✓ | addChild, setChild, removeSubtree |
-| Stack | ✓ (index) | ✓ (index) | ✓ (index) | ✓ | ✓ | - |
-| LinkedList | ✓ (index/id) | ✓ (index/id) | ✓ (index/id) | ✓ | ✓ | addNode, insertNode |
-| Text | ✓ | ✓ | - | - | - | Font methods, alignment, sizing |
+| Data Structure | setValue | setColor | setArrow | setText | add/insert | remove | Special Methods |
+|---------------|----------|----------|----------|---------|------------|--------|----------------|
+| Array | ✓ (index) | ✓ (index) | ✓ (index) | ✓ | ✓ | ✓ | - |
+| Matrix | ✓ (2D) | ✓ (2D) | ✓ (2D) | ✓ | - | - | addRow, addColumn, addBorder |
+| Graph | ✓ (index/id) | ✓ (index/id) | ✓ (index/id) | ✓ | ✓ | ✓ | setHidden (index/id), addEdge, setEdges |
+| Tree | ✓ (index/id) | ✓ (index/id) | ✓ (index/id) | ✓ | ✓ | ✓ | addChild, setChild, removeSubtree |
+| Stack | ✓ (index) | ✓ (index) | ✓ (index) | ✓ | ✓ | ✓ | - |
+| LinkedList | ✓ (index/id) | ✓ (index/id) | ✓ (index/id) | ✓ | ✓ | ✓ | addNode, insertNode |
+| Text | ✓ | ✓ | - | - | - | - | Font methods, alignment, sizing |