Add Dialog Builder fluent API as opt-in extension module

[michaellwest]

Summary

The Read-Variable cmdlet is powerful but requires verbose hashtable construction and manual variable initialization. This proposal adds a Dialog Builder fluent API as an opt-in extension module that wraps Read-Variable with chainable helper functions.

Motivation

Building complex dialogs currently requires:

• Manual hashtable construction for each field parameter
• Explicit variable initialization (especially for Item types)
• Repetitive boilerplate across scripts

The Dialog Builder library reduces this to a fluent, discoverable API.

Before vs After

Before (raw Read-Variable)

$rootItem = Get-Item -Path "master:/content"
$result = Read-Variable -Parameters @(
    @{ Name = "userName"; Title = "User Name"; Value = "" },
    @{ Name = "isActive"; Title = "Active"; Value = $true; Editor = "checkbox" },
    @{ Name = "rootItem"; Title = "Root Item"; Root = "/sitecore/content/" }
) -Title "My Dialog" -Width 500 -Height 400 -ShowHints -OkButtonName "OK" -CancelButtonName "Cancel"

After (Dialog Builder)

Import-Function -Name DialogBuilder

$dialog = New-DialogBuilder -Title "My Dialog" -ShowHints |
    Add-TextField -Name "userName" -Title "User Name" -Mandatory |
    Add-Checkbox -Name "isActive" -Title "Active" -Value $true |
    Add-ItemPicker -Name "rootItem" -Title "Root Item"

$result = Show-Dialog -DialogBuilder $dialog
if ($result -eq "ok") {
    Write-Host "User: $userName, Active: $isActive, Root: $($rootItem.ItemPath)"
}

Function Inventory (25+ functions)

Core: New-DialogBuilder, Add-DialogField, Show-Dialog, Debug-DialogBuilder, Test-DialogBuilder, Copy-DialogBuilder, Remove-DialogField, Export-DialogBuilderConfig

Convenience: Add-TextField (-IsPassword/-IsEmail/-IsNumber), Add-MultiLineTextField, Add-LinkField, Add-Checkbox, Add-TristateCheckbox, Add-RadioButtons, Add-Dropdown, Add-Checklist, Add-DateTimePicker, Add-ItemPicker, Add-Droplink, Add-Droptree, Add-Droplist, Add-GroupedDroplink, Add-GroupedDroplist, Add-TreeList, Add-MultiList, Add-UserPicker, Add-RolePicker, Add-UserRolePicker, Add-InfoText, Add-Marquee, Add-RuleField, Add-RuleActionField

Internal: Show-FieldDebugInfo

Implementation Approach

• Opt-in extension module following the Authorable Reports pattern
• 3 serialized YAML items under Extensions/Dialog Builder/:
  • Dialog Builder (ScriptModule) — enabled by default
  • Functions (ScriptLibrary)
  • DialogBuilder (Script) — contains all function definitions
• Users opt in with: Import-Function -Name DialogBuilder
• No C# changes — pure PowerShell
• No config changes — uses existing functions integration point
• Already covered by Spe.Scripts.module.json (ItemAndDescendants scope)

Key Features

• Automatic variable initialization (handles Item types)
• Type inference for editor selection
• Fluent/chainable API
• Validation support (mandatory fields + custom validators)
• Debug capabilities (Debug-DialogBuilder, Test-DialogBuilder)
• Conditional visibility via GroupId/ParentGroupId
• Column layout and tab support

Source

Full library with documentation: https://gist.github.com/michaellwest/d3ab4841c0e7488f7f98c1c104ed48ee