Separated Select options into their own Option and OptionGroup elements; Added -HelpText for Range, Checkbox, Radio, and Select elements; Added a new Datalist element

docs/Getting-Started/Migrating/08-to-10.md

@@ -153,6 +153,37 @@ Because of this change, functions that had `-Layouts` or `-Elements` parameters
 
 Originally, within the scriptblock of a dynamic element, if you wanted to access the data of an element's parent you could do so via `$ElementData.Parent`. This has now been changed, and the data is accessible via a new `$ParentData` instead - this has been done to stop the `$ElementData` object from getting too large, and to reduce network data transfer to better support SSE.
 
+### Selects
+
+Select elements have been changed primarily in the way you supply Options. Originally you would create a Select via `New-PodeWebSelect` and supply `-Options` as a string array, and optionally `-DisplayOptions` or `-SelectedValue`.
+
+Now, you can create Options via the new `New-PodeWebOption` function - and even group them via `New-PodeWebOptionGroup`. The `-Options` on `New-PodeWebSelect` now accepts an array of these elements, and the `-DisplayOptions` and `-SelectedValue` have moved to `New-PodeWebOption` as `-DisplayName` and `-Selected` respectively.
+
+For example, the following previous Select element:
+
+```powershell
+New-PodeWebSelect -Name 'Example' -Options @('Option1', 'Option2') -SelectedValue 'Option1'
+```
+
+Would now be the following instead:
+
+```powershell
+New-PodeWebSelect -Name 'Example' -Options @(
+    New-PodeWebOption -Name 'Option1' -Selected
+    New-PodeWebOption -Name 'Option2'
+)
+```
+
+To assist with most migrations there is a helper function: `ConvertTo-PodeWebOption`. You can pipe an original raw string array into this, along with an optional `-SelectedOption` value, and it will convert to strings into Option elements for you:
+
+```powershell
+New-PodeWebSelect -Name 'Example' -Options @(
+    @('Option1', 'Option2') | ConvertTo-PodeWebOption -SelectedOption 'Option1'
+)
+```
+
+The `Update-PodeWebSelect` action sees the same update as well. Additionally the `-Value` on `Set-PodeWebSelect` is now `-OptionName`.
+
 ## Classes and Styles
 
 All element functions have had the `-CssClass` and `-CssStyle` parameters removed. Instead, you can now pipe the element into either `Add-PodeWebClass` or `Add-PodeWebStyle`:

docs/Tutorials/Actions/Datalist.md

@@ -0,0 +1,126 @@
+# Datalist
+
+This page details the actions available to Datalist elements.
+
+## Add
+
+To add one or more Options you can use [`Add-PodeWebDatalistOption`](../../../Functions/Actions/Add-PodeWebDatalistOption) along with `-Option`:
+
+```powershell
+New-PodeWebContainer -NoBackground -Content @(
+    New-PodeWebDatalist -Name 'Example' -Options @(
+        New-PodeWebOption -Name 'Option1'
+        New-PodeWebOption -Name 'Option2'
+    )
+
+    New-PodeWebButton -Name 'Add Option' -ScriptBlock {
+        Add-PodeWebDatalistOption -Name 'Example' -Option @(
+            New-PodeWebOption -Name 'Added1'
+        )
+    }
+)
+```
+
+## Clear
+
+To clear the options of a Datalist element, you can use [`Clear-PodeWebDatalist`](../../../Functions/Actions/Clear-PodeWebDatalist):
+
+```powershell
+New-PodeWebContainer -NoBackground -Content @(
+    New-PodeWebDatalist -Name 'Example' -Options @(
+        New-PodeWebOption -Name 'Option1'
+        New-PodeWebOption -Name 'Option2'
+        New-PodeWebOption -Name 'Option3'
+    )
+
+    New-PodeWebButton -Name 'Clear Datalist' -ScriptBlock {
+        Clear-PodeWebDatalist -Name 'Example'
+    }
+)
+```
+
+## Remove
+
+To remove one or more Options you can use [`Remove-PodeWebDatalistOption`](../../../Functions/Actions/Remove-PodeWebDatalistOption) along with `-OptionName`:
+
+```powershell
+New-PodeWebContainer -NoBackground -Content @(
+    New-PodeWebDatalist -Name 'Example' -Options @(
+        New-PodeWebOption -Name 'Option1'
+        New-PodeWebOption -Name 'Option2'
+        New-PodeWebOption -Name 'Option3'
+    )
+
+    New-PodeWebButton -Name 'Remove Options' -ScriptBlock {
+        Remove-PodeWebDatalistOption -Name 'Example' -OptionName 'Option1', 'Option3'
+    }
+)
+```
+
+## Set
+
+To set the currently selected option/value of a Datalist element, you can use [`Set-PodeWebDatalist`](../../../Functions/Actions/Set-PodeWebDatalist). You can either set the value to a predefined option, or to a custom value not in the options list:
+
+```powershell
+New-PodeWebContainer -NoBackground -Content @(
+    New-PodeWebDatalist -Name 'Example' -Options @(
+        New-PodeWebOption -Name 'Option1'
+        New-PodeWebOption -Name 'Option2'
+        New-PodeWebOption -Name 'Option3'
+    )
+
+    New-PodeWebButton -Name 'Update Datalist Predefined' -ScriptBlock {
+        $rand = Get-Random -Minimum 0 -Maximum 3
+        $opt = (@('Option1', 'Option2', 'Option3'))[$rand]
+        Set-PodeWebDatalist -Name 'Example' -Value $opt
+    }
+
+    New-PodeWebButton -Name 'Update Datalist Custom' -ScriptBlock {
+        Set-PodeWebDatalist -Name 'Example' -Value 'Custom Value'
+    }
+)
+```
+
+## Sync
+
+If you built a Datalist element with the `-ScriptBlock` parameter, then you can re-invoke the scriptblock to update the element by using [`Sync-PodeWebDatalist`](../../../Functions/Actions/Sync-PodeWebDatalist):
+
+```powershell
+New-PodeWebContainer -NoBackground -Content @(
+    New-PodeWebDatalist -Name 'Example' -ScriptBlock {
+        foreach ($i in (1..10)) {
+            Get-Random -Minimum 1 -Maximum 10
+        }
+    }
+
+    New-PodeWebButton -Name 'Sync Datalist' -ScriptBlock {
+        Sync-PodeWebDatalist -Name 'Example'
+    }
+)
+```
+
+## Update
+
+You can update a Datalist element's options by using [`Update-PodeWebDatalist`](../../../Functions/Actions/Update-PodeWebDatalist):
+
+```powershell
+New-PodeWebContainer -NoBackground -Content @(
+    New-PodeWebDatalist -Name 'Example' -ScriptBlock {
+        foreach ($i in (1..10)) {
+            Get-Random -Minimum 1 -Maximum 10
+        }
+    }
+
+    New-PodeWebButton -Name 'New Options' -ScriptBlock {
+        $options = @(foreach ($i in (1..10)) {
+            Get-Random -Minimum 1 -Maximum 10
+        })
+
+        $options |
+            ConvertTo-PodeWebOption |
+            Update-PodeWebDatalist -Name 'Example'
+    }
+)
+```
+
+Various other properties can be updated as well.

docs/Tutorials/Actions/Error.md

@@ -14,7 +14,9 @@ New-PodeWebCard -Content @(
         New-PodeWebTextbox -Name 'Name'
         New-PodeWebTextbox -Name 'Password' -Type Password -PrependIcon Lock
         New-PodeWebCheckbox -Name 'Checkboxes' -Options @('Terms', 'Privacy') -AsSwitch
-        New-PodeWebSelect -Name 'Role' -Options @('User', 'Admin', 'Operations') -Multiple
+        New-PodeWebSelect -Name 'Role' -Multiple -Options @(
+            @('User', 'Admin', 'Operations') | ConvertTo-PodeWebOption
+        )
     )
 )
 ```

docs/Tutorials/Actions/Form.md

@@ -12,7 +12,9 @@ New-PodeWebCard -Content @(
         New-PodeWebTextbox -Name 'Name'
         New-PodeWebTextbox -Name 'Password' -Type Password -PrependIcon Lock
         New-PodeWebCheckbox -Name 'Checkboxes' -Options @('Terms', 'Privacy') -AsSwitch
-        New-PodeWebSelect -Name 'Role' -Options @('User', 'Admin', 'Operations') -Multiple
+        New-PodeWebSelect -Name 'Role' -Multiple -Options @(
+            @('User', 'Admin', 'Operations') | ConvertTo-PodeWebOption
+        )
     )
 )
 
@@ -33,7 +35,9 @@ New-PodeWebCard -Content @(
         New-PodeWebTextbox -Name 'Name'
         New-PodeWebTextbox -Name 'Password' -Type Password -PrependIcon Lock
         New-PodeWebCheckbox -Name 'Checkboxes' -Options @('Terms', 'Privacy') -AsSwitch
-        New-PodeWebSelect -Name 'Role' -Options @('User', 'Admin', 'Operations') -Multiple
+        New-PodeWebSelect -Name 'Role' -Multiple -Options @(
+            @('User', 'Admin', 'Operations') | ConvertTo-PodeWebOption
+        )
     )
 )
 

docs/Tutorials/Actions/Select.md

@@ -2,32 +2,101 @@
 
 This page details the actions available to Select elements.
 
+## Add
+
+To add one or more Options, or Option Groups, you can use [`Add-PodeWebSelectOption`](../../../Functions/Actions/Add-PodeWebSelectOption) along with `-Option` and optionally a `-GroupName` to place the options under:
+
+```powershell
+New-PodeWebContainer -NoBackground -Content @(
+    New-PodeWebSelect -Name 'Example' -Options @(
+        New-PodeWebOptionGroup -Name 'Group1' -Options @(
+            New-PodeWebOption -Name 'Option1'
+        )
+        New-PodeWebOption -Name 'Option2'
+    )
+
+    New-PodeWebButton -Name 'Add Option' -ScriptBlock {
+        Add-PodeWebSelectOption -Name 'Example' -Option @(
+            New-PodeWebOption -Name 'Added1'
+        )
+    }
+
+    New-PodeWebButton -Name 'Add Option to Group' -ScriptBlock {
+        Add-PodeWebSelectOption -Name 'Example' -GroupName 'Group1' -Option @(
+            New-PodeWebOption -Name 'Added1'
+        )
+    }
+
+    New-PodeWebButton -Name 'Add Options and Group' -ScriptBlock {
+        Add-PodeWebSelectOption -Name 'Example' -Option @(
+            New-PodeWebOptionGroup -Name 'AddedGroup1' -Options @(
+                New-PodeWebOption -Name 'Added1'
+            )
+        )
+    }
+)
+```
+
 ## Clear
 
 To clear the options of a Select element, you can use [`Clear-PodeWebSelect`](../../../Functions/Actions/Clear-PodeWebSelect):
 
 ```powershell
 New-PodeWebContainer -NoBackground -Content @(
-    New-PodeWebSelect -Name Options -Options Option1, Option2, Option3
+    New-PodeWebSelect -Name 'Example' -Options @(
+        New-PodeWebOption -Name 'Option1'
+        New-PodeWebOption -Name 'Option2'
+        New-PodeWebOption -Name 'Option3'
+    )
 
     New-PodeWebButton -Name 'Clear Select' -ScriptBlock {
-        Clear-PodeWebSelect -Name Options
+        Clear-PodeWebSelect -Name 'Example'
+    }
+)
+```
+
+## Remove
+
+To remove one or more Options, or Option Groups, you can use [`Remove-PodeWebSelectOption`](../../../Functions/Actions/Remove-PodeWebSelectOption) along with `-OptionName` and/or `-GroupName`:
+
+```powershell
+New-PodeWebContainer -NoBackground -Content @(
+    New-PodeWebSelect -Name 'Example' -Options @(
+        New-PodeWebOptionGroup -Name 'Group1' -Options @(
+            New-PodeWebOption -Name 'Option1'
+        )
+        New-PodeWebOptionGroup -Name 'Group2' -Options @(
+            New-PodeWebOption -Name 'Option2'
+            New-PodeWebOption -Name 'Option3'
+        )
+    )
+
+    New-PodeWebButton -Name 'Remove Groups' -ScriptBlock {
+        Remove-PodeWebSelectOption -Name 'Example' -GroupName 'Group1', 'Group2'
+    }
+
+    New-PodeWebButton -Name 'Remove Options' -ScriptBlock {
+        Remove-PodeWebSelectOption -Name 'Example' -OptionName 'Option1', 'Option3'
     }
 )
 ```
 
 ## Set
 
-To set the currently selected option/value of a select element, you can use [`Set-PodeWebSelect`](../../../Functions/Actions/Set-PodeWebSelect):
+To set the currently selected option/value of a Select element, you can use [`Set-PodeWebSelect`](../../../Functions/Actions/Set-PodeWebSelect):
 
 ```powershell
 New-PodeWebContainer -NoBackground -Content @(
-    New-PodeWebSelect -Name Options -Options Option1, Option2, Option3
+    New-PodeWebSelect -Name 'Example' -Options @(
+        New-PodeWebOption -Name 'Option1'
+        New-PodeWebOption -Name 'Option2'
+        New-PodeWebOption -Name 'Option3'
+    )
 
     New-PodeWebButton -Name 'Update Select' -ScriptBlock {
         $rand = Get-Random -Minimum 0 -Maximum 3
         $opt = (@('Option1', 'Option2', 'Option3'))[$rand]
-        Set-PodeWebSelect -Name Options -Value $opt
+        Set-PodeWebSelect -Name 'Example' -OptionName $opt
     }
 )
 ```
@@ -38,14 +107,14 @@ If you built a Select element with the `-ScriptBlock` parameter, then you can re
 
 ```powershell
 New-PodeWebContainer -NoBackground -Content @(
-    New-PodeWebSelect -Name Options --ScriptBlock {
-        return @(foreach ($i in (1..10)) {
+    New-PodeWebSelect -Name 'Example' -ScriptBlock {
+        foreach ($i in (1..10)) {
             Get-Random -Minimum 1 -Maximum 10
-        })
+        }
     }
 
     New-PodeWebButton -Name 'Sync Select' -ScriptBlock {
-        Sync-PodeWebSelect -Name Options
+        Sync-PodeWebSelect -Name 'Example'
     }
 )
 ```
@@ -56,22 +125,22 @@ You can update a Select element's options by using [`Update-PodeWebSelect`](../.
 
 ```powershell
 New-PodeWebContainer -NoBackground -Content @(
-    New-PodeWebSelect -Name Options --ScriptBlock {
-        return @(foreach ($i in (1..10)) {
+    New-PodeWebSelect -Name 'Example' -ScriptBlock {
+        foreach ($i in (1..10)) {
             Get-Random -Minimum 1 -Maximum 10
-        })
+        }
     }
 
     New-PodeWebButton -Name 'New Options' -ScriptBlock {
         $options = @(foreach ($i in (1..10)) {
             Get-Random -Minimum 1 -Maximum 10
         })
 
-        $options | Update-PodeWebSelect -Name Options
+        $options |
+            ConvertTo-PodeWebOption |
+            Update-PodeWebSelect -Name 'Example'
     }
 )
 ```
 
-You can also optionally supply `-DisplayOptions` to alter the values displayed in the Select element, as well as also supply as `-SelectedValue`.
-
 Various other properties can be updated as well.

docs/Tutorials/Actions/Validation.md

@@ -27,7 +27,9 @@ New-PodeWebCard -Content @(
     } -Content @(
         New-PodeWebTextbox -Name 'Username'
         New-PodeWebTextbox -Name 'Password' -Type Password -PrependIcon Lock
-        New-PodeWebSelect -Name 'Role' -Options @('User', 'Admin') -Multiple
+        New-PodeWebSelect -Name 'Role' -Multiple -Options @(
+            @('User', 'Admin') | ConvertTo-PodeWebOption
+        )
     )
 )
 ```

docs/Tutorials/ElementData.md

@@ -12,7 +12,7 @@ New-PodeWebSelect -Name 'Random' -ScriptBlock {
         Get-Random -Minimum 1 -Maximum 10
     })
 
-    $options | Update-PodeWebSelect -Id $ElementData.Id
+    $options | ConvertTo-PodeWebOption | Update-PodeWebSelect -Id $ElementData.Id
 }
 ```