Add documentation for TextFormatter architectural issues and future rewrite plans

Co-authored-by: tig <585482+tig@users.noreply.github.com>

Terminal.Gui/Text/README.md

@@ -0,0 +1,43 @@
+# Text Formatting in Terminal.Gui
+
+This directory contains text formatting and processing classes for Terminal.Gui.
+
+## Classes
+
+### TextFormatter
+
+The main text formatting class that handles:
+- Text alignment (horizontal and vertical)
+- Text direction support (left-to-right, right-to-left, top-to-bottom, etc.)
+- Word wrapping
+- Multi-line text support
+- HotKey processing
+- Wide character (Unicode) support
+
+**Known Issues**: The current `TextFormatter` implementation has several architectural problems that are planned to be addressed in a future rewrite:
+
+1. **Format/Draw Coupling**: The `Draw()` method does significant formatting work, making `FormatAndGetSize()` unreliable
+2. **Performance**: `Format()` is called multiple times during layout operations
+3. **Complex Alignment**: Alignment logic is embedded in drawing code instead of using the `Aligner` engine
+4. **Poor Extensibility**: Adding new features requires modifying the monolithic class
+5. **No Interface**: Prevents multiple text formatter implementations
+
+See [TextFormatter Rewrite Issue](https://github.com/gui-cs/Terminal.Gui/issues/3469) for details.
+
+### Other Classes
+
+- `TextDirection`: Enumeration for text direction support
+- `StringExtensions`: Extension methods for string processing
+- `RuneExtensions`: Extension methods for Unicode Rune processing
+- `NerdFonts`: Support for Nerd Fonts icons
+
+## Future Plans
+
+A complete rewrite of `TextFormatter` is planned that will:
+- Separate formatting from rendering concerns
+- Provide an interface-based architecture for extensibility
+- Improve performance with better caching
+- Support multiple text formats (HTML, Attributed Text, etc.)
+- Use the `Aligner` engine for proper alignment
+
+This is a major architectural change planned for a future release.

Terminal.Gui/Text/TextFormatter.cs

@@ -8,6 +8,16 @@ namespace Terminal.Gui.Text;
 ///     Provides text formatting. Supports <see cref="View.HotKey"/>s, horizontal and vertical alignment, text direction,
 ///     multiple lines, and word-based line wrap.
 /// </summary>
+/// <remarks>
+///     <para>
+///         <strong>NOTE:</strong> This class has known architectural issues that are planned to be addressed in a future rewrite.
+///         See https://github.com/gui-cs/Terminal.Gui/issues/[ISSUE_NUMBER] for details.
+///     </para>
+///     <para>
+///         Known issues include: Format/Draw decoupling problems, performance issues with repeated formatting,
+///         complex alignment implementation, and poor extensibility for advanced text features.
+///     </para>
+/// </remarks>
 public class TextFormatter
 {
     // Utilized in CRLF related helper methods for faster newline char index search.
@@ -86,7 +96,9 @@ public class TextFormatter
 
         if (driver is { })
         {
-            // INTENT: What, exactly, is the intent of this?
+            // INTENT: Calculate the effective drawing area by intersecting screen bounds with maximum container bounds.
+            // This ensures text doesn't draw outside the maximum allowed area.
+            // TODO: This logic is complex and could benefit from clearer naming and documentation.
             maxScreen = maximum == default (Rectangle)
                             ? screen
                             : new (
@@ -493,6 +505,9 @@ public class TextFormatter
         }
 
         // HACK: Fill normally will fill the entire constraint size, but we need to know the actual size of the text.
+        // This is a core architectural problem - formatting and drawing logic are coupled.
+        // This hack temporarily changes alignment to get accurate measurements, then restores it.
+        // TODO: Address this in the planned TextFormatter rewrite by separating formatting from drawing.
         Alignment prevAlignment = Alignment;
 
         if (Alignment == Alignment.Fill)