Merge pull request #588 from Badgerati/themes_new_and_custom

Renames Dark theme to Midnight, and replaces Dark theme with a new Dark theme; Adds new Sepia and Forest inbuilt themes; Adds support for building custom themes directly using Pode.Web functions

.build.ps1

@@ -239,8 +239,8 @@ task MoveLibs {
     }
 
     New-Item -Path "$($libs_path)/highlightjs/styles" -ItemType Directory -Force | Out-Null
-    Copy-Item -Path "$($src_path)/@highlightjs/cdn-assets/styles/tomorrow-night-blue.min.css" -Destination "$($libs_path)/highlightjs/styles/" -Force
-    Copy-Item -Path "$($src_path)/@highlightjs/cdn-assets/styles/default.min.css" -Destination "$($libs_path)/highlightjs/styles/" -Force
+    Copy-Item -Path "$($src_path)/@highlightjs/cdn-assets/styles/a11y-dark.min.css" -Destination "$($libs_path)/highlightjs/styles/" -Force
+    Copy-Item -Path "$($src_path)/@highlightjs/cdn-assets/styles/a11y-light.min.css" -Destination "$($libs_path)/highlightjs/styles/" -Force
 
     # monaco
     New-Item -Path "$($libs_path)/monaco" -ItemType Directory -Force | Out-Null

README.md

@@ -29,7 +29,7 @@ This is a web template framework for use with the [Pode](https://github.com/Badg
 
 It allows you to build web pages purely with PowerShell - no HTML, CSS, or JavaScript knowledge is required!
 
-You can build charts, forms, tables, general text, tabs, login pages, etc. There's a light, dark, and terminal themes, and you can supply a custom CSS file.
+You can build charts, forms, tables, general text, tabs, login pages, etc. There's a light, dark, terminal, and more themes available, and you can supply custom CSS files or build your own in PowerShell.
 
 ## 📦 Libraries
 
@@ -60,7 +60,7 @@ Then navigate to `http://127.0.0.1:8000` in your browser.
 * Or, use a tabs layout for your pages!
 * Show or right code via the Monaco editor (still WIP)
 * Render code in code blocks with code highlighting!
-* Support for Light, Dark, Terminal, and custom themes
+* Support for Light, Dark, Terminal, custom themes, and more
 
 ## 📦 Install
 
@@ -98,7 +98,7 @@ Start-PodeServer {
     Add-PodeEndpoint -Address localhost -Port 8090 -Protocol Http
 
     # set the use of the pode.web templates
-    Use-PodeWebTemplates -Title 'Example' -Theme Dark
+    Use-PodeWebTemplates -Title 'Example' -Theme Midnight
 
     # add the page
     Add-PodeWebPage -Name Processes -Icon Activity -ScriptBlock {

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

@@ -194,3 +194,20 @@ If you would like to have a default root page still set up, but simply redirect
 ## Pode.Web Static Content
 
 This next change should in theory only apply to Pode.Web itself, however, the static content route that Pode.Web used to load images/etc. has changed from `/pode.web` to `/pode.web-static`. If by chance you are using Pode.Web's static content in any of your pages, this is one change to be aware of in case some content stops loading correctly.
+
+## Themes
+
+The original Dark theme has now been renamed to "Midnight", and the Dark theme has now been replaced with a proper dark theme:
+
+![Dark Theme](../../../images/dark_theme.png){ width=48% }
+![Midnight Theme](../../../images/midnight_theme.png){ width=48% }
+
+### Code Editor
+
+The themes for `New-PodeWebCodeEditor` have been changed:
+
+| Old      | New          |
+| -------- | ------------ |
+| vs       | Light        |
+| vs-dark  | Dark         |
+| hc-black | HighContrast |

docs/Tutorials/Themes.md

@@ -1,48 +1,182 @@
 # Themes
 
-Pode.Web comes with some inbuilt themes (including a dark theme!), plus the ability to use custom themes. Themes are set using [`Use-PodeWebTemplates`](../../Functions/Utilities/Use-PodeWebTemplates).
+Pode.Web comes with some inbuilt themes (including a dark theme!), plus the ability to build/use custom themes. Themes are set using [`Use-PodeWebTemplates`](../../Functions/Utilities/Use-PodeWebTemplates), or custom ones can be built using [`Add-PodeWebCustomTheme`](../../Functions/Utilities/Add-PodeWebCustomTheme).
 
 ## Inbuilt
 
-Pode.Web has 4 inbuilt themes:
+Pode.Web has 7 inbuilt themes:
 
 * Light
 * Dark
+* Midnight (dark blue/navy)
+* Sepia (brown)
+* Forest (green)
 * Terminal (black/green)
-* Auto (uses the user's system theme)
+* Auto (use the user's system theme)
 
-For example, to use the `Terminal` theme:
+For example, to use the `Dark` theme:
 
 ```powershell
-Use-PodeWebTemplates -Title 'Example' -Theme Terminal
+Use-PodeWebTemplates -Title 'Example' -Theme Dark
 ```
 
-### Light
+Examples of how the inbuilt themes look are as follows:
 
-![light_theme](../../images/light_theme.png)
+![Light Theme](../../images/light_theme.png){ width=48% }
+![Dark Theme](../../images/dark_theme.png){ width=48% }
+![Midnight Theme](../../images/midnight_theme.png){ width=48% }
+![Sepia Theme](../../images/sepia_theme.png){ width=48% }
+![Forest Theme](../../images/forest_theme.png){ width=48% }
+![Terminal Theme](../../images/terminal_theme.png){ width=48% }
 
-### Dark
+## Custom
 
-![dark_theme](../../images/dark_theme.png)
+There is also a `Custom` theme option that lets you reference, or build, your custom themes via [`Add-PodeWebCustomTheme`](../../Functions/Utilities/Add-PodeWebCustomTheme). You can add multiple custom themes, but the first one will be the initial default custom theme - this can be changed using [`Set-PodeWebCustomThemeDefault`](../../Functions/Utilities/Set-PodeWebCustomThemeDefault).
 
-### Terminal
+### Base Theme
 
-![terminal_theme](../../images/terminal_theme.png)
+Whether you're referencing a custom CSS file, or building your theme using Pode.Web functions, either option allows you to use a "Base" theme to build on top of. You can use a Base theme by supplying one of the inbuilt theme names to the `-Base` parameter on [`Add-PodeWebCustomTheme`](../../Functions/Utilities/Add-PodeWebCustomTheme):
 
-## Custom
+```powershell
+# by URL
+Add-PodeWebCustomTheme -Name 'Custom1' -Base Dark -Url 'https://example.com/custom-theme.css'
+
+# or, building a theme
+Add-PodeWebCustomTheme -Name 'Custom2' -Base Dark `
+    -BackgroundColourConfig (New-PodeWebBackgroundColourConfig -Page 'darkred') `
+    -FontFamily 'wingdings'
+```
 
-And there is also a `Custom` theme option, which will let you add your own custom themes via [`Add-PodeWebCustomTheme`](../../Functions/Utilities/Add-PodeWebCustomTheme), which you can supply a URL for the custom CSS:
+This will allow you to build on top of, or customise, one of Pode.Web's inbuilt themes.
+
+### URL
+
+One option for using a custom theme is to directly create a custom CSS file, and then have Pode.Web use that file by either literal or relative URL:
 
 ```powershell
 Use-PodeWebTemplates -Title 'Example' -Theme Custom
+
+# literal url
 Add-PodeWebCustomTheme -Name 'Custom1' -Url 'https://example.com/custom-theme.css'
+
+# relative url - assuming the CSS file is stored in the "/public" folder
+Add-PodeWebCustomTheme -Name 'Custom1' -Url '/custom-theme.css'
 ```
 
-The first custom theme you add is the default theme.
+### Build
+
+Instead of rolling a custom CSS file, Pode.Web comes with some functions that allow you to build your custom theme by overriding Pode.Web CSS variables. These functions can be used with [`Add-PodeWebCustomTheme`](../../Functions/Utilities/Add-PodeWebCustomTheme) to tailor your theme directly with PowerShell:
+
+| Function                                                                                               | Description                                                            |
+| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| [`New-PodeWebBackgroundColourConfig`](../../Functions/Utilities/New-PodeWebBackgroundColourConfig)     | Allows you to override base background colours                         |
+| [`New-PodeWebBorderColourConfig`](../../Functions/Utilities/New-PodeWebBorderColourConfig)             | Allows you to override base border colours                             |
+| [`New-PodeWebTextColourConfig`](../../Functions/Utilities/New-PodeWebTextColourConfig)                 | Allows you to override base text colours                               |
+| [`New-PodeWebNavColourConfig`](../../Functions/Utilities/New-PodeWebNavColourConfig)                   | Allows you to override colours specific to the top Navigation header   |
+| [`New-PodeWebToastColourConfig`](../../Functions/Utilities/New-PodeWebToastColourConfig)               | Allows you to override colours specific to Toast messages              |
+| [`New-PodeWebCalendarIconColourConfig`](../../Functions/Utilities/New-PodeWebCalendarIconColourConfig) | Allows you to override colours specific to Calendar icons on textboxes |
+| [`New-PodeWebChartColourConfig`](../../Functions/Utilities/New-PodeWebChartColourConfig)               | Allows you to override colours specific to Charts                      |
+
+!!! note
+    Each function accepts a colour to customise the theme, colours must be supplied in either hex, rgb, rgba, or named format. For example: `#111`, `#1a3e4f`, `dodgerblue`, `rgb(255, 0, 0)`, or `rgba(255, 0, 0, 0.5)`.
+
+Let's say you want to use the Dark theme as a base, and change the Page background to "darkred" and the font-family to "wingdings" (because why not!):
+
+```powershell
+Use-PodeWebTemplates -Title 'Example' -Theme Custom
+Add-PodeWebCustomTheme -Name 'Custom1' -Base Dark `
+    -BackgroundColourConfig (New-PodeWebBackgroundColourConfig -Page 'darkred') `
+    -FontFamily 'wingdings'
+```
+
+Only the parameters you supply will be applied and override the base theme - in this case, the Page background colour and the font-family, and all other colours will come from the base Dark theme:
+
+![custom_dark_theme](../../images/custom_dark_theme.png)
+
+A fuller example, still using the Dark theme as a base, would be as follows. Here we supply nearly all possible configuration to build a custom darkred theme:
+
+```powershell
+Use-PodeWebTemplates -Title 'Test' -Logo '/pode.web-static/images/icon.png' -Theme Custom
+
+$bgColourConfig = @{
+    Page      = '#000'
+    Hero      = '#210000'
+    Primary   = '#1a0000'
+    Secondary = '#1f0000'
+    Tertiary  = '#240000'
+}
+$bgColourConfig = New-PodeWebBackgroundColourConfig @bgColourConfig
+
+$borderColourConfig = @{
+    Primary   = '#4c0000'
+    Secondary = '#ba0000'
+    Tertiary  = '#4c0000'
+}
+$borderColourConfig = New-PodeWebBorderColourConfig @borderColourConfig
+
+$txtColourConfig = @{
+    Primary        = '#afafaf'
+    Secondary      = '#afafaf'
+    Tertiary       = '#d6d6d6'
+    Link           = '#ff2f2f'
+    HoverPrimary   = '#ff2f2f'
+    HoverSecondary = '#dedede'
+    Disabled       = '#959595'
+    Enabled        = '#1a0000'
+}
+$txtColourConfig = New-PodeWebTextColourConfig @txtColourConfig
+
+$navColourConfig = @{
+    Background = '#2f0000'
+    Border     = '#4c0000'
+    Text       = '#e3e3e3'
+    HoverText  = '#ff1a1a'
+}
+$navColourConfig = New-PodeWebNavColourConfig @navColourConfig
+
+$toastColourConfig = @{
+    BackgroundPrimary   = '#1f0000'
+    BackgroundSecondary = '#3a0000'
+    Border              = '#614d4d'
+    TextPrimary         = '#bcbcbc'
+    TextSecondary       = '#d6d6d6'
+}
+$toastColourConfig = New-PodeWebToastColourConfig @toastColourConfig
+
+$calColourConfig = @{
+    Primary = 'invert(0%)'
+    Hover   = 'invert(100%) sepia() brightness(30%) saturate(10000%) hue-rotate(120deg)'
+}
+$calColourConfig = New-PodeWebCalendarIconColourConfig @calColourConfig
+
+$chartColourConfig = @{
+    Point  = @('#ff4a4a', '#bd10e0', '#4a90e2', '#b8e986', '#ffdab9')
+    Grid   = '#4c0000'
+    Tick   = '#afafaf'
+    Border = '#4c0000'
+}
+$chartColourConfig = New-PodeWebChartColourConfig @chartColourConfig
+
+Add-PodeWebCustomTheme -Name 'DarkRed' -Base Dark `
+    -BackgroundColourConfig $bgColourConfig `
+    -BorderColourConfig $borderColourConfig `
+    -TextColourConfig $txtColourConfig `
+    -NavColourConfig $navColourConfig `
+    -ToastColourConfig $toastColourConfig `
+    -CalendarIconColourConfig $calColourConfig `
+    -ChartColourConfig $chartColourConfig
+```
+
+which looks as follows:
+
+![custom_darkred_theme](../../images/custom_darkred_theme.png)
+
+#### Calendar Icons
+Above it was mentioned that colours are supplied in hex, rgb, etc. formats. However, for calendar icon colours, configured via [`New-PodeWebCalendarIconColourConfig`](../../Functions/Utilities/New-PodeWebCalendarIconColourConfig), the format is very different. Here, you need to a format such as `invert(100%) sepia() brightness(60%) saturate(10000%) hue-rotate(60deg)`. Further information about this format can be [found here](https://developer.mozilla.org/en-US/docs/Web/CSS/filter).
 
 ## Set the Theme
 
-You can override the default theme on a per user basis, by either setting the `pode.web.theme` cookie on the frontend, or by setting a `Theme` property in the user's authentication object:
+You can override the default theme on a per-user basis by either setting the `pode.web.theme` cookie on the frontend, or by setting a `Theme` property in the user's authentication object:
 
 ```powershell
 New-PodeAuthScheme -Form | Add-PodeAuth -Name Example -ScriptBlock {

docs/index.md

@@ -11,7 +11,7 @@ This is a web template framework for use with the [Pode](https://github.com/Badg
 
 It allows you to build web pages purely with PowerShell - no HTML, CSS, or JavaScript knowledge is required!
 
-You can build charts, forms, tables, general text, tabs, login pages, etc. There's a light, dark, and terminal themes, and you can supply a custom CSS file.
+You can build charts, forms, tables, general text, tabs, login pages, etc. There's a light, dark, terminal, and more themes available, and you can supply custom CSS files or build your own in PowerShell.
 
 [![GetStarted](https://img.shields.io/badge/-Get%20Started!-green.svg?longCache=true&style=for-the-badge)](./Getting-Started/Installation)
 [![QuickLook](https://img.shields.io/badge/-Quick%20Look!-blue.svg?longCache=true&style=for-the-badge)](#quick-look)
@@ -29,7 +29,7 @@ You can build charts, forms, tables, general text, tabs, login pages, etc. There
 * Or, use a tabs layout for your pages!
 * Show or write code via the Monaco editor (still WIP)
 * Render code in code blocks with code highlighting!
-* Support for Light, Dark, Terminal, and custom themes
+* Support for Light, Dark, Terminal, custom themes, and more
 
 ## 📦 Libraries
 
@@ -45,7 +45,7 @@ Import-Module Pode.Web
 Start-PodeServer {
     Add-PodeEndpoint -Address localhost -Port 8080 -Protocol Http
 
-    Use-PodeWebTemplates -Title 'Example' -Theme Dark
+    Use-PodeWebTemplates -Title 'Example' -Theme Midnight
 
     Add-PodeWebPage -Name 'Services' -Icon 'Settings' -ScriptBlock {
         New-PodeWebCard -Content @(

examples/alerts.ps1

@@ -7,7 +7,7 @@ Start-PodeServer {
     New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging
 
     # set the use of templates, and set a login page
-    Use-PodeWebTemplates -Title 'Inputs' -Theme Dark
+    Use-PodeWebTemplates -Title 'Alerts' -Theme Dark
 
     # set the home page controls (just a simple paragraph)
     $card = New-PodeWebCard -Content @(

examples/badges.ps1

@@ -0,0 +1,25 @@
+Import-Module Pode -MaximumVersion 2.99.99 -Force
+Import-Module ..\src\Pode.Web.psm1 -Force
+
+Start-PodeServer {
+    # add a simple endpoint
+    Add-PodeEndpoint -Address localhost -Port 8090 -Protocol Http
+    New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging
+
+    # set the use of templates, and set a login page
+    Use-PodeWebTemplates -Title 'Badges' -Theme Dark
+
+    # set the home page controls (just a simple paragraph)
+    $card = New-PodeWebCard -Content @(
+        New-PodeWebBadge -Value 'Primary' -Colour Blue
+        New-PodeWebBadge -Value 'Secondary' -Colour Grey
+        New-PodeWebBadge -Value 'Success' -Colour Green
+        New-PodeWebBadge -Value 'Danger' -Colour Red
+        New-PodeWebBadge -Value 'Warning' -Colour Yellow
+        New-PodeWebBadge -Value 'Info' -Colour Cyan
+        New-PodeWebBadge -Value 'Light' -Colour Light
+        New-PodeWebBadge -Value 'Dark' -Colour Dark
+    )
+
+    Add-PodeWebPage -Name 'Home' -Path '/' -HomePage -Content $card -Title 'Badges'
+}

examples/basic.ps1

@@ -23,7 +23,7 @@ Start-PodeServer {
     # add a page to search process (output as json in an appended textbox)
     $form = New-PodeWebForm -Name 'Search' -ShowReset -SubmitText 'Search' -ResetText 'Clear' -AsCard -ScriptBlock {
         $procs = @(Get-Process -Name $WebEvent.Data.Name -ErrorAction Ignore |
-            Select-Object Name, ID, WorkingSet, CPU)
+                Select-Object Name, ID, WorkingSet, CPU)
 
         $procs |
             New-PodeWebTextbox -Name 'Output' -Multiline -Preformat -AsJson -Size ((6 * $procs.Length) + 2) |

examples/buttons.ps1

@@ -0,0 +1,35 @@
+Import-Module Pode -MaximumVersion 2.99.99 -Force
+Import-Module ..\src\Pode.Web.psm1 -Force
+
+Start-PodeServer {
+    # add a simple endpoint
+    Add-PodeEndpoint -Address localhost -Port 8090 -Protocol Http
+    New-PodeLoggingMethod -Terminal | Enable-PodeErrorLogging
+
+    # set the use of templates, and set a login page
+    Use-PodeWebTemplates -Title 'Buttons' -Theme Dark
+
+    # set the home page controls (just a simple paragraph)
+    $card = New-PodeWebCard -Content @(
+        New-PodeWebButton -Name 'Primary' -Colour Blue -ScriptBlock {}
+        New-PodeWebButton -Name 'Secondary' -Colour Grey -ScriptBlock {}
+        New-PodeWebButton -Name 'Success' -Colour Green -ScriptBlock {}
+        New-PodeWebButton -Name 'Danger' -Colour Red -ScriptBlock {}
+        New-PodeWebButton -Name 'Warning' -Colour Yellow -ScriptBlock {}
+        New-PodeWebButton -Name 'Info' -Colour Cyan -ScriptBlock {}
+        New-PodeWebButton -Name 'Light' -Colour Light -ScriptBlock {}
+        New-PodeWebButton -Name 'Dark' -Colour Dark -ScriptBlock {}
+    )
+    $card2 = New-PodeWebCard -Content @(
+        New-PodeWebButton -Name 'Primary_O' -Colour Blue -ScriptBlock {} -Outline
+        New-PodeWebButton -Name 'Secondary_O' -Colour Grey -ScriptBlock {} -Outline
+        New-PodeWebButton -Name 'Success_O' -Colour Green -ScriptBlock {} -Outline
+        New-PodeWebButton -Name 'Danger_O' -Colour Red -ScriptBlock {} -Outline
+        New-PodeWebButton -Name 'Warning_O' -Colour Yellow -ScriptBlock {} -Outline
+        New-PodeWebButton -Name 'Info_O' -Colour Cyan -ScriptBlock {} -Outline
+        New-PodeWebButton -Name 'Light_O' -Colour Light -ScriptBlock {} -Outline
+        New-PodeWebButton -Name 'Dark_O' -Colour Dark -ScriptBlock {} -Outline
+    )
+
+    Add-PodeWebPage -Name 'Home' -Path '/' -HomePage -Content $card, $card2 -Title 'Buttons'
+}