From 60fbcc9ebd3acb92c63f8c42ee3be549cff905f0 Mon Sep 17 00:00:00 2001 From: AJ Date: Thu, 11 Jan 2024 16:15:39 -0800 Subject: [PATCH] Add docs on text formatting --- docs/guide.md | 174 +++++++++++++++++- .../ajalt/mordant/terminal/HtmlRenderer.kt | 4 +- 2 files changed, 166 insertions(+), 12 deletions(-) diff --git a/docs/guide.md b/docs/guide.md index 064ca517..58e572cb 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -29,7 +29,8 @@ combine a foreground and background. ``` === "Output" -
⏺ ⏺ ⏺  +
+
● ● ● 
     You can use any of the standard ANSI colors
     You can nest styles arbitrarily
@@ -49,6 +50,151 @@ you can do this:
 Terminal(AnsiLevel.TRUECOLOR)
 ```
 
+## Text Wrapping and Alignment
+
+`Terminal.println` will preserve whitespace by default, but you can use the [`Text`][Text] widget
+for more advanced formatting. You can use the [Whitespace], [TextAlign], and [OverflowWrap] enums to
+format text. They behave similar to the CSS properties of the same names.
+
+### Text Wrapping
+
+Pass one of the [Whitespace] values to the `Text` constructor to control how whitespace is handled.
+You can also set a `width` to wrap the text to a specific width rather than the terminal width.
+
+=== "Code"
+    ```kotlin
+    val text = """
+    This is a long line {
+        This line is indented
+    }
+    """.trimIndent()
+
+    for (entry in Whitespace.entries) {
+        terminal.println(
+            Panel(
+                content = Text(text, whitespace = entry, width = 17),
+                title = Text(entry.name)
+            )
+        )
+    }
+    ```
+
+=== "Output"
+
+    

+    
● ● ● 

+    
+    ╭──── NORMAL ────╮
+    │This is a long  │
+    │line { This line│
+    │is indented }   │
+    ╰────────────────╯
+    ╭────────────────── NOWRAP ───────────────────╮
+    │This is a long line { This line is indented }│
+    ╰─────────────────────────────────────────────╯
+    ╭────────── PRE ──────────╮
+    │This is a long line {    │
+    │    This line is indented│
+    │}                        │
+    ╰─────────────────────────╯
+    ╭─── PRE_WRAP ───╮
+    │This is a long  │
+    │line {          │
+    │    This line is│
+    │indented        │
+    │}               │
+    ╰────────────────╯
+    ╭── PRE_LINE ──╮
+    │This is a long│
+    │line {        │
+    │This line is  │
+    │indented      │
+    │}             │
+    ╰──────────────╯
+    

+    

+
+!!! tip
+    You can format styled text too.
+
+    ```kotlin
+    Text(red("Hello, world!"), whitespace = NORMAL)
+    ```
+
+### Text Alignment
+
+You can use the [TextAlign] values to align or justify text.
+
+=== "Code"
+    ```kotlin
+    for (entry in TextAlign.entries) {
+        terminal.println(
+            Text(
+                (black on blue)("align = ${entry.name}"),
+                align = entry, width = 20
+            ),
+        )
+    }
+    ```
+
+=== "Output"
+    

+    
● ● ● 

+    
+    align = LEFT        
+           align = RIGHT
+       align = CENTER   
+    align   =    JUSTIFY
+    align = NONE
+    

+    

+
+
+### Text Overflow
+
+If you are wrapping text that has long words that exceed the line length by themselves, you can use
+the [OverflowWrap] enum to control how they are handled.
+
+=== "Code"
+    ```kotlin
+    for (entry in OverflowWrap.entries) {
+        terminal.println(
+            Panel(
+                content = Text(
+                    "overflow_wrap",
+                    whitespace = Whitespace.NORMAL,
+                    overflowWrap = entry,
+                    width = 8
+                ),
+                title = Text(entry.name)
+            )
+        )
+    }
+    ```
+
+=== "Output"
+    

+    
● ● ● 

+    
+    ╭── NORMAL ───╮
+    │overflow_wrap│
+    ╰─────────────╯
+    ╭ BREAK_WORD ─╮
+    │overflow     │
+    │_wrap        │
+    ╰─────────────╯
+    ╭─ TRUNCATE ──╮
+    │overflow     │
+    ╰─────────────╯
+    ╭─ ELLIPSES ──╮
+    │overflo…     │
+    ╰─────────────╯
+    

+    

+
+!!! note
+    `OverflowWrap` has no effect when used with `Whitespace.PRE` or `Whitespace.NOWRAP`.
+
 ## Tables
 
 Use the [table] DSL to define table widgets.
@@ -62,7 +208,8 @@ Use the [table] DSL to define table widgets.
     ```
 
 === "Output"
-    
⏺ ⏺ ⏺ 
+    

+    
● ● ● 

     
     ┌──────────┬──────────┐
     │ Column 1 │ Column 2 │
@@ -76,7 +223,8 @@ Mordant gives you lots of customization for your tables, including striped row s
 column spans, and different border styles.
 
 === "Output"
-    
⏺ ⏺ ⏺ 
+    

+    
● ● ● 

     
                                                                   Percent Change  
                                       2020      2021      2022   2020-21  2021-21 
@@ -157,13 +305,12 @@ column spans, and different border styles.
         }
         captionBottom(dim("via U.S. Bureau of Labor Statistics"))
     }
-    ``` 
+    ```
 
 ## Layout
 
 If you need to lay out multiple widgets or strings, you can use the [grid] builder, which has an API
-similar to `table`, but doesn't apply styling by default. 
-
+similar to `table`, but doesn't apply styling by default
 === "Code"
     ```kotlin
     grid {
@@ -177,7 +324,8 @@ similar to `table`, but doesn't apply styling by default.
     ```
 
 === "Output"
-    
⏺ ⏺ ⏺ 
+    

+    
● ● ● 

     
     Grid Builder Supports Alignment
     Left          Center      Right
@@ -196,7 +344,8 @@ There are also the [horizontalLayout] and [verticalLayout] builders if you don't
     ```
 
 === "Output"
-    
⏺ ⏺ ⏺ 
+    

+    
● ● ● 

     
     Spinner: ⠹
     

@@ -238,7 +387,7 @@ string with [Terminal.textAnimation].
         a.update(it)
         Thread.sleep(25)
     }
-    ``` 
+    ```
 
 === "Output"
     ![](img/animation.svg)
@@ -261,7 +410,8 @@ You can create customizable progress bars that automatically compute speed and t
     }
     ```
 === "Output"
-    
⏺ ⏺ ⏺ 
+    

+    
● ● ● 

     
     my-file.iso 83% ━━━━━━━━━━━━━━━━━━ ━━━ 25.0/30.0G 71.2MB/s  eta 0:01:10
     

@@ -300,6 +450,7 @@ creating a subclass of the [Prompt] class. Mordant includes [StringPrompt], [Yes
 
 
 [ConfirmationPrompt]:       api/mordant/com.github.ajalt.mordant.terminal/-confirmation-prompt/index.html
+[OverflowWrap]:             api/mordant/com.github.ajalt.mordant.rendering/-overflow-wrap/index.html
 [Prompt]:                   api/mordant/com.github.ajalt.mordant.terminal/-prompt/index.html
 [README]:                   https://github.com/ajalt/clikt
 [StringPrompt]:             api/mordant/com.github.ajalt.mordant.terminal/-string-prompt/index.html
@@ -307,8 +458,11 @@ creating a subclass of the [Prompt] class. Mordant includes [StringPrompt], [Yes
 [Terminal.prompt]:          api/mordant/com.github.ajalt.mordant.terminal/-terminal/prompt.html
 [Terminal.textAnimation]:   api/mordant/com.github.ajalt.mordant.animation/text-animation.html
 [Terminal]:                 api/mordant/com.github.ajalt.mordant.terminal/-terminal/index.html
+[TextAlign]:                api/mordant/com.github.ajalt.mordant.rendering/-text-align/index.html
 [TextColors]:               api/mordant/com.github.ajalt.mordant.rendering/-text-colors/index.html
 [TextStyles]:               api/mordant/com.github.ajalt.mordant.rendering/-text-styles/index.html
+[Text]:                     api/mordant/com.github.ajalt.mordant.widgets/-text/index.html
+[Whitespace]:               api/mordant/com.github.ajalt.mordant.rendering/-whitespace/index.html
 [YesNoPrompt]:              api/mordant/com.github.ajalt.mordant.terminal/-yes-no-prompt/index.html
 [color.bg]:                 api/mordant/com.github.ajalt.mordant.rendering/-text-style/bg.html
 [color.on]:                 api/mordant/com.github.ajalt.mordant.rendering/-text-style/on.html
diff --git a/mordant/src/commonMain/kotlin/com/github/ajalt/mordant/terminal/HtmlRenderer.kt b/mordant/src/commonMain/kotlin/com/github/ajalt/mordant/terminal/HtmlRenderer.kt
index 31a07d66..9e086518 100644
--- a/mordant/src/commonMain/kotlin/com/github/ajalt/mordant/terminal/HtmlRenderer.kt
+++ b/mordant/src/commonMain/kotlin/com/github/ajalt/mordant/terminal/HtmlRenderer.kt
@@ -29,11 +29,11 @@ fun TerminalRecorder.outputAsHtml(
         append("padding: 0.5em 1em;")
         append("filter: drop-shadow(0.5em 0.5em 0.5em black);")
         append("background-color: ${backgroundColor.formatCssString()};")
-        append("""">""")
+        append("""">\n
""")
         for (color in listOf(SRGB("#ff5f56"), SRGB("#ffbd2e"), SRGB("#27c93f"))) {
             append("""⏺ """)
         }
-        appendLine()
+        appendLine("
")
     }
     append("""
""")
     if (includeCodeTag) append("")