More updates for ANSIBuilder and TerminalCapability

Author: stalep

content/docs/readline/color-detection.md

@@ -93,6 +93,8 @@ int errorText = cap.getSuggestedErrorCode();        // 31 or 91 (red variants)
 int successText = cap.getSuggestedSuccessCode();    // 32 or 92 (green variants)
 int warningText = cap.getSuggestedWarningCode();    // 33 or 93 (yellow variants)
 int infoText = cap.getSuggestedInfoCode();          // 34 or 94 (blue variants)
+int debugText = cap.getSuggestedDebugCode();        // 90 or 37 (gray/white variants)
+int traceText = cap.getSuggestedTraceCode();        // 90 (gray - least prominent)
 int timestampText = cap.getSuggestedTimestampCode(); // 36 or 96 (cyan variants)
 int messageText = cap.getSuggestedMessageCode();     // 35 or 95 (magenta variants)
 
@@ -109,9 +111,14 @@ connection.write("\u001B[" + errorText + "mError: Something went wrong\u001B[0m\
 | `getSuggestedSuccessCode()` | 92 (bright green) | 32 (green) | Success messages |
 | `getSuggestedWarningCode()` | 93 (bright yellow) | 33 (yellow) | Warnings |
 | `getSuggestedInfoCode()` | 94 (bright blue) | 34 (blue) | Info messages |
+| `getSuggestedDebugCode()` | 37 (white) | 90 (gray) | Debug messages |
+| `getSuggestedTraceCode()` | 90 (gray) | 90 (gray) | Trace messages (least prominent) |
 | `getSuggestedTimestampCode()` | 96 (bright cyan) | 36 (cyan) | Timestamps in logs |
 | `getSuggestedMessageCode()` | 95 (bright magenta) | 35 (magenta) | Highlighted messages |
 
+The log level colors follow a prominence hierarchy from most to least visible:
+**ERROR > WARN > INFO > DEBUG > TRACE**
+
 ### Customizing Suggested Colors
 
 You can override the default suggested colors using the `Builder`:
@@ -139,6 +146,8 @@ TerminalColorCapability custom = TerminalColorCapability.builder()
     .successCode(46)
     .warningCode(208)
     .infoCode(39)
+    .debugCode(250)      // 256-color light gray
+    .traceCode(240)      // 256-color dark gray
     .timestampCode(244)
     .messageCode(255)
     .foregroundCode(252)
@@ -480,8 +489,8 @@ ANSIBuilder builder = ANSIBuilder.builder(cap);
 // Log line with timestamp, level, and message
 connection.write(builder
     .timestamp("2024-01-15 10:30:45").append(" ")
-    .success("[INFO]").append(" ")
-    .message("Application started successfully")
+    .error("[ERROR]").append(" ")
+    .append("Connection to database failed")
     .toLine());
 
 builder.reset();
@@ -494,12 +503,26 @@ connection.write(builder
 builder.reset();
 connection.write(builder
     .timestamp("2024-01-15 10:30:47").append(" ")
-    .error("[ERROR]").append(" ")
-    .append("Connection to database failed")
+    .info("[INFO]").append(" ")
+    .message("Application started successfully")
+    .toLine());
+
+builder.reset();
+connection.write(builder
+    .timestamp("2024-01-15 10:30:48").append(" ")
+    .debug("[DEBUG]").append(" ")
+    .append("Configuration loaded from /etc/app.conf")
+    .toLine());
+
+builder.reset();
+connection.write(builder
+    .timestamp("2024-01-15 10:30:49").append(" ")
+    .trace("[TRACE]").append(" ")
+    .append("Entering method processRequest()")
     .toLine());
 ```
 
-Output adapts automatically to the terminal theme - bright colors on dark backgrounds, normal colors on light backgrounds.
+Output adapts automatically to the terminal theme - bright colors on dark backgrounds, normal colors on light backgrounds. Debug and trace use subdued colors (white/gray) to be less prominent than the colored log levels.
 
 ### Color Depth Adaptation
 

content/docs/readline/terminal-colors.md

@@ -126,11 +126,15 @@ import org.aesh.terminal.utils.TerminalColorCapability;
 // Detect terminal capabilities
 TerminalColorCapability cap = TerminalColorDetector.detect(connection);
 
-// Get theme-appropriate colors
+// Get theme-appropriate colors for log levels
 TerminalColor error = TerminalColor.forError(cap);          // Red
 TerminalColor success = TerminalColor.forSuccess(cap);      // Green
 TerminalColor warning = TerminalColor.forWarning(cap);      // Yellow
 TerminalColor info = TerminalColor.forInfo(cap);            // Cyan/Blue
+TerminalColor debug = TerminalColor.forDebug(cap);          // White/Gray (subdued)
+TerminalColor trace = TerminalColor.forTrace(cap);          // Gray (least prominent)
+
+// Other semantic colors
 TerminalColor highlight = TerminalColor.forHighlight(cap);  // Emphasized
 TerminalColor muted = TerminalColor.forMuted(cap);          // Dimmed
 TerminalColor timestamp = TerminalColor.forTimestamp(cap);  // Cyan (for log timestamps)
@@ -145,11 +149,15 @@ TerminalColor message = TerminalColor.forMessage(cap);      // Magenta (for high
 | `forSuccess()` | Bright green | Normal green | Success messages |
 | `forWarning()` | Bright yellow | Normal yellow | Warnings |
 | `forInfo()` | Bright cyan | Normal blue | Info messages |
+| `forDebug()` | White | Gray | Debug messages (subdued) |
+| `forTrace()` | Gray | Gray | Trace messages (least prominent) |
 | `forHighlight()` | Bright white | Black | Emphasized text |
 | `forMuted()` | Normal white | Normal black | Secondary text |
 | `forTimestamp()` | Bright cyan | Normal cyan | Log timestamps |
 | `forMessage()` | Bright magenta | Normal magenta | Highlighted messages |
 
+Log level colors follow a prominence hierarchy: **ERROR > WARN > INFO > DEBUG > TRACE**
+
 These methods ensure readable colors on any background. On dark themes, bright colors stand out. On light themes, normal intensity prevents eye strain.
 
 ### Example: Status Messages
@@ -275,15 +283,20 @@ String output = builder
 
 ### Semantic Color Methods
 
-The builder provides theme-aware semantic colors:
+The builder provides theme-aware semantic colors for log levels:
 
 ```java
 ANSIBuilder builder = ANSIBuilder.builder(cap);
 
+// Log level colors (most to least prominent)
 builder.error("Error message");      // Red (bright on dark, normal on light)
-builder.success("Success message");  // Green
 builder.warning("Warning message");  // Yellow
+builder.success("Success message");  // Green
 builder.info("Info message");        // Blue
+builder.debug("Debug message");      // White/Gray (subdued)
+builder.trace("Trace message");      // Gray (least prominent)
+
+// Other semantic colors
 builder.timestamp("10:30:45");       // Cyan (subdued, for log timestamps)
 builder.message("Highlighted");      // Magenta (for highlighted messages)
 ```