Add documentation for TextPath widget

spectreconsole · Feb 27, 2022 · 75a0ee6 · 75a0ee6
1 parent eb4a7d3
commit 75a0ee6
Show file tree

Hide file tree

Showing 9 changed files with 151 additions and 3 deletions.
diff --git a/docs/Program.cs b/docs/Program.cs
@@ -38,6 +38,7 @@ await Bootstrapper.Factory
                 .AddShortcode("ColorTable", typeof(ColorTableShortcode))
                 .AddShortcode("EmojiTable", typeof(EmojiTableShortcode))
                 .AddShortcode("Alert", typeof(AlertShortcode))
+                .AddShortcode("Info", typeof(InfoShortcode))
                 .AddShortcode("AsciiCast", typeof(AsciiCastShortcode))
                 .AddShortcode("Example", typeof(ExampleSnippet))
                 .AddPipelines()

diff --git a/docs/input/assets/casts/text-path-plain.cast b/docs/input/assets/casts/text-path-plain.cast
@@ -0,0 +1,6 @@
+{"version": 2, "width": 42, "height": 23, "title": "text-path (plain)", "env": {"TERM": "Spectre.Console"}}
+[0, "o", "\u001B[37m\u250C\u2500Windows path\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[37m\u2502\u001B[0m                                      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m C:/.../That/Will/Be/Truncated.txt    \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m                                      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"]
+[0.015, "o", "\u001B[37m\u250C\u2500Unix path\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[37m\u2502\u001B[0m                                      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m /.../That/Will/Be/Truncated.txt      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m                                      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"]
+[0.015, "o", "\u001B[37m\u250C\u2500Styling\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[37m\u2502\u001B[0m                                      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m \u001B[32m/\u001B[0m\u001B[37m...\u001B[0m\u001B[31m/\u001B[0m\u001B[37mThat\u001B[0m\u001B[31m/\u001B[0m\u001B[37mWill\u001B[0m\u001B[31m/\u001B[0m\u001B[37mBe\u001B[0m\u001B[31m/\u001B[0m\u001B[34mTruncated.txt\u001B[0m      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m                                      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"]
+[0.015, "o", "\u001B[37m\u250C\u2500Alignment\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[37m\u2502\u001B[0m                                      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m /.../That/Will/Be/Truncated.txt      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m   /.../That/Will/Be/Truncated.txt    \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m      /.../That/Will/Be/Truncated.txt \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m                                      \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"]
+
diff --git a/docs/input/assets/casts/text-path-rich.cast b/docs/input/assets/casts/text-path-rich.cast
@@ -0,0 +1,6 @@
+{"version": 2, "width": 42, "height": 23, "title": "text-path (rich)", "env": {"TERM": "Spectre.Console"}}
+[0, "o", "\u001B[38;5;8m\u250C\u2500Windows path\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m                                      \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m C:/\u2026/Path/That/Will/Be/Truncated.txt \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m                                      \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"]
+[0, "o", "\u001B[38;5;8m\u250C\u2500Unix path\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m                                      \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m /\u2026/Path/That/Will/Be/Truncated.txt   \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m                                      \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"]
+[0, "o", "\u001B[38;5;8m\u250C\u2500Styling\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m                                      \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m \u001B[38;5;2m/\u001B[0m\u001B[38;5;11m\u2026\u001B[0m\u001B[38;5;9m/\u001B[0m\u001B[38;5;11mPath\u001B[0m\u001B[38;5;9m/\u001B[0m\u001B[38;5;11mThat\u001B[0m\u001B[38;5;9m/\u001B[0m\u001B[38;5;11mWill\u001B[0m\u001B[38;5;9m/\u001B[0m\u001B[38;5;11mBe\u001B[0m\u001B[38;5;9m/\u001B[0m\u001B[38;5;12mTruncated.txt\u001B[0m   \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m                                      \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"]
+[0, "o", "\u001B[38;5;8m\u250C\u2500Alignment\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m                                      \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m /\u2026/Path/That/Will/Be/Truncated.txt   \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m  /\u2026/Path/That/Will/Be/Truncated.txt  \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m   /\u2026/Path/That/Will/Be/Truncated.txt \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m                                      \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"]
+
diff --git a/docs/input/tailwind.css b/docs/input/tailwind.css
@@ -24,6 +24,14 @@ and the ascii terminal player.
     @apply m-0;
 }
 
+.alert-info {
+    @apply p-4 border border-green-300 bg-green-100 text-green-800 dark:border-green-700/50 dark:bg-green-800/50 dark:text-gray-300/90 rounded shadow-sm  text-sm;
+}
+
+.alert-info p {
+    @apply m-0;
+}
+
 [type='search'] {
     @apply shadow-sm focus:ring-indigo-300 focus:border-indigo-300 block w-full sm:text-sm border-gray-300 rounded-md;
 }

diff --git a/docs/input/widgets/path.md b/docs/input/widgets/path.md
@@ -0,0 +1,71 @@
+Title: Text Path
+Order: 80
+Description: "The **TextPath** class is used to render a horizontal rule (line) to the terminal."
+Highlights:
+    - Automatically shrinks paths to fit.
+    - Custom colors for segments of the path.
+    - Specify left, center or right aligned paths.
+Reference: T:Spectre.Console.TextPath
+
+---
+
+The `TextPath` class is used to render a Windows or Unix disk path.
+
+<?# AsciiCast cast="text-path" /?>
+
+## Usage
+
+```csharp
+var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt");
+
+AnsiConsole.Write(path);
+```
+
+## Alignment
+
+```csharp
+var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt");
+path.Alignment = Justify.Right;
+
+AnsiConsole.Write(path);
+```
+
+You can also specify styles via extension methods:
+
+```csharp
+var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt")
+    .RightAligned();
+```
+
+## Styling
+
+All the segments in the path can be customized to have different styles.
+
+```csharp
+var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt");
+
+path.RootStyle = new Style(foreground: Color.Red);
+path.SeparatorStyle = new Style(foreground: Color.Green);
+path.StemStyle = new Style(foreground: Color.Blue);
+path.LeafStyle = new Style(foreground: Color.Yellow);
+```
+
+You can also specify styles via extension methods:
+
+```csharp
+var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt")
+    .RootStyle(new Style(foreground: Color.Red))
+    .SeparatorStyle(new Style(foreground: Color.Green))
+    .StemStyle(new Style(foreground: Color.Blue))
+    .LeafStyle(new Style(foreground: Color.Yellow));
+```
+
+Or just set the colors via extension methods:
+
+```csharp
+var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt")
+    .RootColor(Color.Red)
+    .SeparatorColor(Color.Green)
+    .StemColor(Color.Blue)
+    .LeafColor(Color.Yellow);
+```
diff --git a/docs/package-lock.json b/docs/package-lock.json
diff --git a/docs/src/Shortcodes/InfoShortcode.cs b/docs/src/Shortcodes/InfoShortcode.cs
@@ -0,0 +1,13 @@
+using System.Collections.Generic;
+using Statiq.Common;
+
+namespace Docs.Shortcodes
+{
+    public class InfoShortcode : SyncShortcode
+    {
+        public override ShortcodeResult Execute(KeyValuePair<string, string>[] args, string content, IDocument document, IExecutionContext context)
+        {
+            return $"<div class=\"alert-info\">{content}</div>";
+        }
+    }
+}
diff --git a/resources/scripts/Generator/Commands/AsciiCast/Samples/TextPathSample.cs b/resources/scripts/Generator/Commands/AsciiCast/Samples/TextPathSample.cs
@@ -0,0 +1,44 @@
+using DocExampleGenerator;
+using Spectre.Console;
+
+namespace Generator.Commands.Samples
+{
+    internal class TextPathSample : BaseSample
+    {
+        public override (int Cols, int Rows) ConsoleSize => (40, 23);
+
+        public override void Run(IAnsiConsole console)
+        {
+            console.Write(
+                new Panel(
+                    new Padder(new TextPath("C:/This/Is/A/Super/Long/Path/That/Will/Be/Truncated.txt"), new Padding(0,1)))
+                .BorderStyle(new Style(foreground: Color.Grey))
+                .Header("Windows path"));
+
+            console.Write(
+                new Panel(
+                    new Padder(new TextPath("/This/Is/A/Super/Long/Path/That/Will/Be/Truncated.txt"), new Padding(0,1)))
+                .BorderStyle(new Style(foreground: Color.Grey))
+                .Header("Unix path"));
+
+            console.Write(
+                new Panel(
+                    new Padder(new TextPath("/This/Is/A/Long/Path/That/Will/Be/Truncated.txt")
+                        .RootColor(Color.Green)
+                        .SeparatorColor(Color.Red)
+                        .StemColor(Color.Yellow)
+                        .LeafColor(Color.Blue), new Padding(0,1)))
+                .BorderStyle(new Style(foreground: Color.Grey))
+                .Header("Styling"));
+
+            console.Write(
+                new Panel(
+                    new Padder(new Rows(
+                        new TextPath("/This/Is/A/Long/Path/That/Will/Be/Truncated.txt").LeftAligned(),
+                        new TextPath("/This/Is/A/Long/Path/That/Will/Be/Truncated.txt").Centered(),
+                        new TextPath("/This/Is/A/Long/Path/That/Will/Be/Truncated.txt").RightAligned()), new Padding(0,1)))
+                .BorderStyle(new Style(foreground: Color.Grey))
+                .Header("Alignment"));
+        }
+    }
+}
diff --git a/src/Spectre.Console/Extensions/TextPathExtensions.cs b/src/Spectre.Console/Extensions/TextPathExtensions.cs
@@ -84,7 +84,7 @@ public static TextPath StemStyle(this TextPath obj, Style style)
     /// <param name="obj">The path.</param>
     /// <param name="color">The stem color.</param>
     /// <returns>The same instance so that multiple calls can be chained.</returns>
-    public static TextPath StemStyle(this TextPath obj, Color color)
+    public static TextPath StemColor(this TextPath obj, Color color)
     {
         return StemStyle(obj, new Style(foreground: color));
     }
@@ -112,7 +112,7 @@ public static TextPath LeafStyle(this TextPath obj, Style style)
     /// <param name="obj">The path.</param>
     /// <param name="color">The leaf color.</param>
     /// <returns>The same instance so that multiple calls can be chained.</returns>
-    public static TextPath LeafStyle(this TextPath obj, Color color)
+    public static TextPath LeafColor(this TextPath obj, Color color)
     {
         return LeafStyle(obj, new Style(foreground: color));
     }