Fix docs and make markup alignable

PwshSpectreConsole/private/Start-AnsiConsoleLive.ps1

@@ -20,9 +20,9 @@ function Start-AnsiConsoleLive {
     New-Variable -Name $resultVariableName -Scope "Script"
     [Spectre.Console.AnsiConsole]::Live($Data).Start({
             param (
-                $ctx
+                [Spectre.Console.LiveDisplayContext] $Context
             )
-            Set-Variable -Name $resultVariableName -Value (& $ScriptBlock $ctx) -Scope "Script"
+            Set-Variable -Name $resultVariableName -Value (& $ScriptBlock $Context) -Scope "Script"
         })
     return Get-Variable -Name $resultVariableName -ValueOnly
 }

PwshSpectreConsole/private/Write-SpectreHostInternal.ps1

@@ -1,17 +1,34 @@
+using module ".\completions\Completers.psm1"
 
 # Functions required for unit testing write-spectrehost
 function Write-SpectreHostInternalMarkup {
     param (
         [Parameter(Mandatory)]
-        [string] $Message
+        [string] $Message,
+        [ValidateSet([SpectreConsoleJustify], ErrorMessage = "Value '{0}' is invalid. Try one of: {1}")]
+        [string]$Justify = "Left",
+        [switch] $PassThru
     )
-    [Spectre.Console.AnsiConsoleExtensions]::Markup([Spectre.Console.AnsiConsole]::Console, $Message)
+    $output = [Spectre.Console.Markup]::new($Message)
+    $output.Justification = [Spectre.Console.Justify]::$Justify
+    if ($PassThru) {
+        return $output
+    }
+    [Spectre.Console.AnsiConsole]::Write($output)
 }
 
 function Write-SpectreHostInternalMarkupLine {
     param (
         [Parameter(Mandatory)]
-        [string] $Message
+        [string] $Message,
+        [ValidateSet([SpectreConsoleJustify], ErrorMessage = "Value '{0}' is invalid. Try one of: {1}")]
+        [string]$Justify = "Left",
+        [switch] $PassThru
     )
-    [Spectre.Console.AnsiConsoleExtensions]::MarkupLine([Spectre.Console.AnsiConsole]::Console, $Message)
+    $output = [Spectre.Console.Markup]::new($Message)
+    $output.Justification = [Spectre.Console.Justify]::$Justify
+    if ($PassThru) {
+        return $output
+    }
+    [Spectre.Console.AnsiConsole]::WriteLine($output)
 }

PwshSpectreConsole/public/config/Set-SpectreColors.ps1

@@ -22,7 +22,7 @@ function Set-SpectreColors {
     The default table text color to set. Must be a valid Spectre Console color name. Defaults to "Default" which will be the standard console foreground color.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to set the accent color and default value color for Spectre Console.
     Write-SpectreRule "This is a default rule"
     Set-SpectreColors -AccentColor "Turquoise2"

PwshSpectreConsole/public/demo/Get-SpectreDemoColors.ps1

@@ -9,7 +9,7 @@
     It also provides information on how to use the colors as parameters for commands or in Spectre Console markup.
 
 .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to use Get-SpectreDemoColors to display a list of the built-in Spectre Console colors.
     Get-SpectreDemoColors
 #>

PwshSpectreConsole/public/demo/Get-SpectreDemoEmoji.ps1

@@ -11,7 +11,7 @@
     Limit the number of emoji returned. This is only really useful for generating the help docs.
 
 .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to use Get-SpectreDemoEmoji to display a list of the built-in Spectre Console emojis.
     Get-SpectreDemoEmoji -Count 5
 

PwshSpectreConsole/public/demo/Get-SpectreDemoFeatures.ps1

@@ -6,7 +6,7 @@
     This script demonstrates the features of Spectre.Console. It shows off the various colors, styles, and other features that Spectre.Console supports.
 
 .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to use Get-SpectreDemoFeatures to display a list of the features of Spectre.Console as seen on the https://spectreconsole.net/ homepage.
     Get-SpectreDemoFeatures
 #>

PwshSpectreConsole/public/demo/Start-SpectreDemo.ps1

@@ -37,7 +37,7 @@ function Start-SpectreDemo {
     ![Spectre demo animation](/demo.gif)
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to run the PwshSpectreConsole demo.
     Start-SpectreDemo
     #>

PwshSpectreConsole/public/demo/Start-SpectreRecording.ps1

@@ -22,7 +22,7 @@ function Start-SpectreRecording {
         .PARAMETER CountdownAndClear
             If this switch is present, the console will be cleared and a countdown will be displayed before the recording starts.
         .EXAMPLE
-            # **Example 1**
+            # **Example 1**  
             # This example demonstrates how to record the spectre console output.
             $recording = Start-SpectreRecording -RecordingType "Html" -CountdownAndClear
             # Use spectre console functions, these will be recorded

PwshSpectreConsole/public/demo/Stop-SpectreRecording.ps1

@@ -14,7 +14,7 @@ function Stop-SpectreRecording {
         .PARAMETER OutputPath
             The path to save the recording to.
         .EXAMPLE
-            # **Example 1**
+            # **Example 1**  
             # This example demonstrates how to record the spectre console output.
             $recording = Start-SpectreRecording -RecordingType "Html" -CountdownAndClear
             # Use spectre console functions, these will be recorded

PwshSpectreConsole/public/formatting/Add-SpectreTableRow.ps1

@@ -14,8 +14,7 @@ The table to which the row will be added.
 An array of renderable items containing the data to be displayed in the columns of this row.
 
 .EXAMPLE
-# **Example 1**
-# This example demonstrates how to add a row to an existing Spectre Console table.
+# **Example 1**  # This example demonstrates how to add a row to an existing Spectre Console table.
 $data = @(
     [pscustomobject]@{Name="John"; Age=25; City="New York"},
     [pscustomobject]@{Name="Jane"; Age=30; City="Los Angeles"}

PwshSpectreConsole/public/formatting/Format-SpectreAligned.ps1

@@ -19,7 +19,7 @@ function Format-SpectreAligned {
     The vertical alignment of the object.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to align a string to the right inside a panel.
     "hello right hand side" | Format-SpectreAligned -HorizontalAlignment Right -VerticalAlignment Middle | Format-SpectrePanel -Expand -Height 9
     #>

PwshSpectreConsole/public/formatting/Format-SpectreBarChart.ps1

@@ -23,7 +23,7 @@ function Format-SpectreBarChart {
     Hides the values from being displayed on the chart.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to display a bar chart of various data points.
     $data = @()
 

PwshSpectreConsole/public/formatting/Format-SpectreBreakdownChart.ps1

@@ -23,7 +23,7 @@ function Format-SpectreBreakdownChart {
     Hides the tag values on the chart.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to display a breakdown chart of various data points.
     $data = @()
 

PwshSpectreConsole/public/formatting/Format-SpectreColumns.ps1

@@ -20,7 +20,7 @@ function Format-SpectreColumns {
     A switch to expand the columns to fill the available space.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to display a collection of strings in columns.
     @("lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing", "elit,", "sed", "do", "eiusmod",
       "tempor", "incididunt", "ut", "labore", "et", "dolore", "magna", "aliqua.", "Ut", "enim", "ad", "minim",
@@ -30,12 +30,12 @@ function Format-SpectreColumns {
       "cupidatat", "non", "proident", "sunt", "in", "culpa") | Foreach-Object { $_ } | Format-SpectreColumns
 
     .EXAMPLE
-    # **Example 2**
+    # **Example 2**  
     # This example demonstrates how to display a collection of panels that are expanded but with normal sized columns.
     @("left", "middle", "right") | Foreach-Object { $_ | Format-SpectrePanel -Expand } | Format-SpectreColumns
 
     .EXAMPLE
-    # **Example 3**
+    # **Example 3**  
     # This example demonstrates how to display a collection of panels that are expanded and with expanded columns so it takes up the console width.
     @("left", "middle", "right") | Foreach-Object { $_ | Format-SpectrePanel -Expand } | Format-SpectreColumns -Expand
     #>

PwshSpectreConsole/public/formatting/Format-SpectreException.ps1

@@ -33,8 +33,7 @@ The style to use when rendering the exception provided as a hashtable. e.g.
 ```
 
 .EXAMPLE
-# **Example 1**
-# This example demonstrates how to format an exception into a Spectre Console Exception with syntax highlighting.
+# **Example 1**  # This example demonstrates how to format an exception into a Spectre Console Exception with syntax highlighting.
 try {
     Get-ChildItem -BadParam -ErrorAction Stop
 } catch {

PwshSpectreConsole/public/formatting/Format-SpectreGrid.ps1

@@ -10,12 +10,12 @@ function Format-SpectreGrid {
     See https://spectreconsole.net/widgets/grid for more information.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to display a grid of rows using the Spectre Console module with a list of lists.
     Format-SpectreGrid -Data @("hello", "I", "am"), @("a", "grid", "of"), @("rows", "using", "spectre")
 
     .EXAMPLE
-    # **Example 2**
+    # **Example 2**  
     # This example demonstrates how to display a grid of rows using the Spectre Console module with a list of `New-SpectreGridRow` objects.
     # The `New-SpectreGridRow` function is used to create the rows when you want to avoid array collapsing in PowerShell turning your rows into a single array of columns.
     $rows = 4

PwshSpectreConsole/public/formatting/Format-SpectreJson.ps1

@@ -71,7 +71,7 @@ function Format-SpectreJson {
     ```
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to format an array of objects into a Spectre Console Json object with syntax highlighting.
     $data = @(
         [pscustomobject]@{

PwshSpectreConsole/public/formatting/Format-SpectrePadded.ps1

@@ -13,17 +13,17 @@ function Format-SpectrePadded {
     A renderable item to wrap in padding.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to pad an item with a padding of 1 on all sides
     "Item to pad" | Format-SpectrePadded -Padding 1 | Format-SpectrePanel
 
     .EXAMPLE
-    # **Example 2**
+    # **Example 2**  
     # This example demonstrates how to pad an item with a padding of 4 on all sides
     "Item to pad" | Format-SpectrePadded -Padding 4  | Format-SpectrePanel
 
     .EXAMPLE
-    # **Example 3**
+    # **Example 3**  
     # This example demonstrates how to pad an item with different padding on each side.
     "Item to pad" | Format-SpectrePadded -Top 4 -Left 10 -Right 1 -Bottom 1 | Format-SpectrePanel
     #>

PwshSpectreConsole/public/formatting/Format-SpectrePanel.ps1

@@ -32,12 +32,12 @@ function Format-SpectrePanel {
     The height of the panel.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to display a panel with a title and a rounded border.
     Format-SpectrePanel -Data "Hello, world!" -Title "My Panel" -Border "Rounded" -Color "Red"
 
     .EXAMPLE
-    # **Example 2**
+    # **Example 2**  
     # This example demonstrates how to display a panel with a title and a double border that's expanded to take up the whole console width.
     "Hello, big panel!" | Format-SpectrePanel -Title "My Big Panel" -Border "Double" -Color "Magenta1" -Expand
     #>

PwshSpectreConsole/public/formatting/Format-SpectreRows.ps1

@@ -14,12 +14,12 @@ function Format-SpectreRows {
     An array of renderable items containing the data to be displayed in the rows.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to display a collection of strings in rows.
     @("top", "middle", "bottom") | Format-SpectreRows
 
     .EXAMPLE
-    # **Example 2**
+    # **Example 2**  
     # This example demonstrates how to display a collection of renderable items as rows inside a panel, without wrapping the renderables in rows you cannot display them in a panel because a panel only accepts a single item.
     $rows = @()
     for ($i = 0; $i -lt 12; $i+= 4) {

PwshSpectreConsole/public/formatting/Format-SpectreTable.ps1

@@ -63,7 +63,7 @@ function Format-SpectreTable {
     Take up all of the horizontal space available.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to format an array of objects into a Spectre Console table.
     $data = @(
         [pscustomobject]@{Name="John"; Age=25; City="New York"},
@@ -72,7 +72,7 @@ function Format-SpectreTable {
     Format-SpectreTable -Data $data
 
     .EXAMPLE
-    # **Example 2**
+    # **Example 2**  
     # This example demonstrates how to format an array of objects into a Spectre Console table with custom properties generated by scriptblock expressions.
     $Properties = @(
         # foreground + background
@@ -85,12 +85,12 @@ function Format-SpectreTable {
     Get-ChildItem | Format-SpectreTable -Property $Properties -AllowMarkup
 
     .EXAMPLE
-    # **Example 3**
+    # **Example 3**  
     # This example demonstrates how to format an array of scalar objects into a Spectre Console table.
     1..10 | Format-SpectreTable -Title Numbers
 
     .EXAMPLE
-    # **Example 4**
+    # **Example 4**  
     # This example demonstrates how to nest other renderable objects inside a table.
     $calendar = Write-SpectreCalendar -Date (Get-Date) -PassThru
 

PwshSpectreConsole/public/formatting/Format-SpectreTextPath.ps1

@@ -14,7 +14,7 @@ function Format-SpectreTextPath {
     The directory/file path to format
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to format a PowerShell path as a Spectre Console Path with syntax highlighting.
     Get-Location | Format-SpectreTextPath | Out-SpectreHost
     #>

PwshSpectreConsole/public/formatting/Format-SpectreTree.ps1

@@ -20,7 +20,7 @@ function Format-SpectreTree {
     The color to use for the tree. This can be a Spectre Console color name or a hex color code. Default is the accent color defined in the script.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to display a tree with multiple children.
     $calendar = Write-SpectreCalendar -Date 2024-07-01 -PassThru
     $data = @{

PwshSpectreConsole/public/formatting/New-SpectreChartItem.ps1

@@ -19,8 +19,7 @@ The value for the chart item.
 The color for the chart item. Must be a valid Spectre color as name, hex or a Spectre.Console.Color object.
 
 .EXAMPLE
-# **Example 1**
-# This example demonstrates how to use SpectreChartItems to create a breakdown chart.
+# **Example 1**  # This example demonstrates how to use SpectreChartItems to create a breakdown chart.
 $data = @()
 $data += New-SpectreChartItem -Label "Sales" -Value 1000 -Color "green"
 $data += New-SpectreChartItem -Label "Expenses" -Value 500 -Color "#ff0000"

PwshSpectreConsole/public/formatting/New-SpectreGridRow.ps1

@@ -8,9 +8,11 @@ Creates a new SpectreGridRow object with the specified columns for use in Format
 .PARAMETER Data
 An array of renderable items containing the data to be displayed in the columns of this row.
 
+.PARAMETER Justify
+The justification to apply to each data item in this row. The default is Left.
+
 .EXAMPLE
-# **Example 1**
-# This example demonstrates how to create a grid with two rows and three columns.
+# **Example 1**  # This example demonstrates how to create a grid with two rows and three columns.
 $columns = @()
 $columns += "Column 1" | Format-SpectrePanel
 $columns += "Column 2" | Format-SpectrePanel
@@ -26,7 +28,7 @@ $rows | Format-SpectreGrid
 function New-SpectreGridRow {
     [Reflection.AssemblyMetadata("title", "New-SpectreGridRow")]
     param (
-        [Parameter(Mandatory)]
+        [Parameter(ValueFromPipeline, Mandatory)]
         [array]$Data
     )
 

PwshSpectreConsole/public/formatting/New-SpectreLayout.ps1

@@ -28,8 +28,7 @@ e.g. in the example below to update the contents of row1 you would use `$root =
 The minimum size of the layout, this can be used to ensure a layout is at least the minimum width.
 
 .EXAMPLE
-# **Example 1**
-# This example demonstrates how to create a layout with a calendar, a list of files, and a panel with a calendar aligned to the middle and center.
+# **Example 1**  # This example demonstrates how to create a layout with a calendar, a list of files, and a panel with a calendar aligned to the middle and center.
 $calendar = Write-SpectreCalendar -Date (Get-Date) -PassThru
 $files = Get-ChildItem | Format-SpectreTable | Format-SpectreAligned -HorizontalAlignment Right -VerticalAlignment Bottom
 

PwshSpectreConsole/public/images/Get-SpectreImage.ps1

@@ -14,7 +14,7 @@ function Get-SpectreImage {
     The maximum width of the image. If not specified, the image will be displayed at its original size.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to display an image in the console.
     Get-SpectreImage -ImagePath ".\private\images\smiley.png" -MaxWidth 40
     #>

PwshSpectreConsole/public/images/Get-SpectreImageExperimental.ps1

@@ -27,12 +27,12 @@ function Get-SpectreImageExperimental {
     The resampling algorithm to use when scaling the image. Valid values are "Bicubic" and "NearestNeighbor". The default value is "Bicubic".
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to display an animated image in the console that loops 4 times.
     Get-SpectreImageExperimental -ImagePath ".\private\images\harveyspecter.gif" -LoopCount 4 -Width 82
 
     .EXAMPLE
-    # **Example 2**
+    # **Example 2**  
     # This example demonstrates how to display a static image in the console.
     Get-SpectreImageExperimental -ImagePath ".\private\images\smiley.png" -Width 80
     #>

PwshSpectreConsole/public/progress/Add-SpectreJob.ps1

@@ -21,7 +21,7 @@ function Add-SpectreJob {
     The PowerShell job to add to the context.
 
     .EXAMPLE
-    # **Example 1**
+    # **Example 1**  
     # This example demonstrates how to add two jobs to a context and wait for them to complete.
     $jobOutcomes = Invoke-SpectreCommandWithProgress -ScriptBlock {
         param (