Workspaces YAML config (#1048)

Added a declarative config for the workspaces. This lets users specify the name and layout engines of workspaces.

This reuses the existing `layout_engines` config options.

The documentation was updated to no longer serve the `_includes` (formerly `_common`) directory.

docs/_includes/core/workspace-overview.md

@@ -0,0 +1,5 @@
+A "workspace" or <xref:Whim.IWorkspace> in Whim is a collection of windows displayed on a single monitor. The layouts of workspaces are determined by their [layout engines](../../configure/core/layout-engines.md). Each workspace has a single active layout engine, and can cycle through different layout engines. <!-- markdownlint-disable-line MD041 -->
+
+There must be at least as many workspaces defined in the config as there are monitors connected to the system. If there are more workspaces defined than monitors, workspaces named `Workspace {workspaces.Count + 1}` will be created for the extra monitors. If there are fewer workspaces defined than monitors, the extra monitors will not have any workspaces displayed on them.
+
+When Whim exits, it will save the current workspaces and the current positions of each window within them. When Whim is started again, it will attempt to merge the saved workspaces with the workspaces defined in the config.

docs/configure/core/styling.md

@@ -1,3 +1,3 @@
 # Styling
 
-[!INCLUDE [Styling](../../_common/core/styling.md)]
+[!INCLUDE [Styling](../../_includes/core/styling.md)]

docs/configure/core/workspaces.md

@@ -1,3 +1,26 @@
 # Workspaces
 
-👷🏗️🚧
+[!INCLUDE[Workspace overview](../../_includes/core/workspace-overview.md)]
+
+## Configuration
+
+The `workspaces` property is a list of workspaces that can be displayed on a monitor. Each workspace has a name and a list of layout engines. The layout engines determine how windows are displayed on the workspace. If no layout engines are provided, the workspace will default to the layout engines defined in [Layout Engines](layout-engines.md).
+
+```yaml
+workspaces:
+  entries:
+    - name: Browser
+      layout_engines:
+        - type: SliceLayoutEngine
+          variant:
+            type: column
+        - type: SliceLayoutEngine
+          variant:
+            type: row
+        - type: TreeLayoutEngine
+
+    - name: IDE
+    - name: Chat
+    - name: Spotify
+    - name: Other
+```

docs/configure/plugins/command-palette.md

@@ -23,7 +23,7 @@ plugins:
 | `max_width_pixels`   | The maximum width of the command palette in pixels.                              |
 | `y_position_percent` | The y position of the command palette as a percentage of the monitor height.     |
 
-[!INCLUDE [Commands](../../_common/plugins/command-palette.md)]
+[!INCLUDE [Commands](../../_includes/plugins/command-palette.md)]
 
 ## Tree Layout
 

docs/configure/plugins/focus-indicator.md

@@ -172,4 +172,4 @@ The color can be any valid RGB or RGBA hex color. The following named colors are
 | `yellow`               | `#FFFFFF00` | <span style="background:#FFFF00" class="color-block"></span>         |
 | `yellow_green`         | `#FF9ACD32` | <span style="background:#9ACD32" class="color-block"></span>         |
 
-[!INCLUDE [Commands](../../_common/plugins/focus-indicator.md)]
+[!INCLUDE [Commands](../../_includes/plugins/focus-indicator.md)]

docs/configure/plugins/gaps.md

@@ -24,4 +24,4 @@ plugins:
 | `default_outer_delta` | The default outer gap used by commands `gaps.outer.increase` and `gaps.outer.decrease` |
 | `default_inner_delta` | The default inner gap used by commands `gaps.inner.increase` and `gaps.inner.decrease` |
 
-[!INCLUDE [Commands](../../_common/plugins/gaps.md)]
+[!INCLUDE [Commands](../../_includes/plugins/gaps.md)]

docs/configure/plugins/layout-preview.md

@@ -16,4 +16,4 @@ plugins:
 | ------------ | -------------------------------------------------- |
 | `is_enabled` | Whether the plugin is enabled. Defaults to `true`. |
 
-[!INCLUDE [Commands](../../_common/plugins/layout-preview.md)]
+[!INCLUDE [Commands](../../_includes/plugins/layout-preview.md)]

docs/configure/plugins/slice-layout.md

@@ -4,4 +4,4 @@ The `SliceLayoutPlugin` is automatically loaded when the `SliceLayoutEngine` is
 
 ## Commands
 
-[!INCLUDE [Commands](../../_common/plugins/slice-layout.md)]
+[!INCLUDE [Commands](../../_includes/plugins/slice-layout.md)]

docs/configure/plugins/tree-layout.md

@@ -4,4 +4,4 @@ The `TreeLayoutPlugin` is automatically loaded when the `TreeLayoutEngine` is us
 
 ## Commands
 
-[!INCLUDE [Commands](../../_common/plugins/tree-layout.md)]
+[!INCLUDE [Commands](../../_includes/plugins/tree-layout.md)]

docs/configure/plugins/updater.md

@@ -18,4 +18,4 @@ plugins:
 | `release_channel`  | The release channel to use. Options are `alpha`, `beta`, and `stable`. Default is `alpha`.                  |
 | `update_frequency` | How often to check for updates. Options are `never`, `daily`, `weekly`, and `monthly`. Default is `weekly`. |
 
-[!INCLUDE [Commands](../../_common/plugins/updater.md)]
+[!INCLUDE [Commands](../../_includes/plugins/updater.md)]

docs/docfx.json

@@ -20,7 +20,7 @@
     "content": [
       {
         "files": ["**/*.{md,yml}"],
-        "exclude": ["_site/**"]
+        "exclude": ["_site/**", "_includes/**"]
       }
     ],
     "resource": [

docs/script/core/styling.md

@@ -1,3 +1,3 @@
 # Styling
 
-[!INCLUDE [Styling](../../_common/core/styling.md)] <!-- markdownlint-disable-line MD041 -->
+[!INCLUDE [Styling](../../_includes/core/styling.md)] <!-- markdownlint-disable-line MD041 -->

docs/script/core/workspaces.md

@@ -1,6 +1,8 @@
 # Workspaces
 
-A "workspace" or <xref:Whim.IWorkspace> in Whim is a collection of windows displayed on a single monitor. The layouts of workspaces are determined by their [layout engines](layout-engines.md). Each workspace has a single active layout engine, and can cycle through different layout engines.
+[!INCLUDE[Workspace overview](../../_includes/core/workspace-overview.md)]
+
+## Configuration
 
 The <xref:Whim.SetCreateLayoutEnginesTransform> lets you specify the default layout engines for workspaces. For example, the following config sets up three workspaces, and two layout engines:
 
@@ -38,10 +40,6 @@ context.Store.Dispatch(
 
 The available layout engines are listed in [Layout Engines](./layout-engines.md).
 
-If no name is provided, the name will default to `Workspace {workspaces.Count + 1}.`
-
-When Whim exits, it will save the current workspaces and the current positions of each window within them. When Whim is started again, it will attempt to merge the saved workspaces with the workspaces defined in the config.
-
 ## Example Command
 
 ```csharp

docs/script/plugins/command-palette.md

@@ -35,4 +35,4 @@ void DoConfig(IContext context)
 return DoConfig;
 ```
 
-[!INCLUDE [Commands](../../_common/plugins/command-palette.md)]
+[!INCLUDE [Commands](../../_includes/plugins/command-palette.md)]

docs/script/plugins/focus-indicator.md

@@ -30,4 +30,4 @@ void DoConfig(IContext context)
 return DoConfig;
 ```
 
-[!INCLUDE [Commands](../../_common/plugins/focus-indicator.md)]
+[!INCLUDE [Commands](../../_includes/plugins/focus-indicator.md)]

docs/script/plugins/gaps.md

@@ -29,4 +29,4 @@ void DoConfig(IContext context)
 return DoConfig;
 ```
 
-[!INCLUDE [Commands](../../_common/plugins/gaps.md)]
+[!INCLUDE [Commands](../../_includes/plugins/gaps.md)]

docs/script/plugins/layout-preview.md

@@ -33,4 +33,4 @@ return DoConfig;
 
 ```
 
-[!INCLUDE [Commands](../../_common/plugins/layout-preview.md)]
+[!INCLUDE [Commands](../../_includes/plugins/layout-preview.md)]

docs/script/plugins/slice-layout.md

@@ -28,4 +28,4 @@ void DoConfig(IContext context)
 return DoConfig;
 ```
 
-[!INCLUDE [Commands](../../_common/plugins/slice-layout.md)]
+[!INCLUDE [Commands](../../_includes/plugins/slice-layout.md)]

docs/script/plugins/tree-layout.md

@@ -30,4 +30,4 @@ void DoConfig(IContext context)
 return DoConfig;
 ```
 
-[!INCLUDE [Commands](../../_common/plugins/tree-layout.md)]
+[!INCLUDE [Commands](../../_includes/plugins/tree-layout.md)]

docs/script/plugins/updater.md

@@ -32,4 +32,4 @@ void DoConfig(IContext context)
 return DoConfig;
 ```
 
-[!INCLUDE [Commands](../../_common/plugins/updater.md)]
+[!INCLUDE [Commands](../../_includes/plugins/updater.md)]

src/Whim.Yaml.Tests/Layouts/YamlLayoutEngineLoaderTests.cs

@@ -101,7 +101,7 @@ public void Load_FocusLayoutEngine(string config, bool maximize, bool isYaml, IC
 		// Then the layout engine is loaded
 		Assert.True(result);
 
-		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
+		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx)!;
 		Assert.Single(engines);
 		engines[0].Should().BeEquivalentTo(new FocusLayoutEngine(engines[0].Identity, maximize));
 	}
@@ -148,7 +148,46 @@ public void Load_InvalidFocusLayoutEngine(string config, bool isYaml, IContext c
 		// Then the layout engine is not loaded
 		Assert.True(result);
 
-		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
-		Assert.Empty(engines);
+		ILayoutEngine[]? engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
+		Assert.Null(engines);
+	}
+
+	public static TheoryData<string, bool> NoLayoutEnginesConfig =>
+		new()
+		{
+			{
+				"""
+					layout_engines:
+					  entries: []
+					""",
+				true
+			},
+			{
+				"""
+					{
+						"layout_engines": {
+							"entries": []
+						}
+					}
+					""",
+				false
+			},
+		};
+
+	[Theory, MemberAutoSubstituteData<YamlLoaderCustomization>(nameof(NoLayoutEnginesConfig))]
+	public void Load_NoLayoutEngines(string config, bool isYaml, IContext ctx)
+	{
+		// Given an invalid config with FocusLayoutEngine set
+		ctx.PluginManager.LoadedPlugins.Returns([]);
+		YamlLoaderTestUtils.SetupFileConfig(ctx, config, isYaml);
+
+		// When loading the layout engine
+		bool result = YamlLoader.Load(ctx);
+
+		// Then the layout engine is not loaded
+		Assert.True(result);
+
+		ILayoutEngine[]? engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
+		Assert.Null(engines);
 	}
 }

src/Whim.Yaml.Tests/Layouts/YamlLayoutEngineLoader_SliceLayoutEngineTests.cs

@@ -53,7 +53,7 @@ public void Load_ColumnLayoutEngine(string config, bool isYaml, IContext ctx, IS
 		// Then the layout engine is loaded
 		Assert.True(result);
 
-		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
+		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx)!;
 		Assert.Single(engines);
 		SliceLayouts.CreateColumnLayout(ctx, plugin, engines[0].Identity).Should().BeEquivalentTo(engines[0]);
 	}
@@ -103,7 +103,7 @@ public void Load_RowLayoutEngine(string config, bool isYaml, IContext ctx, ISlic
 		// Then the layout engine is loaded
 		Assert.True(result);
 
-		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
+		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx)!;
 		Assert.Single(engines);
 		SliceLayouts.CreateRowLayout(ctx, plugin, engines[0].Identity).Should().BeEquivalentTo(engines[0]);
 	}
@@ -153,7 +153,7 @@ public void Load_PrimaryStackLayoutEngine(string config, bool isYaml, IContext c
 		// Then the layout engine is loaded
 		Assert.True(result);
 
-		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
+		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx)!;
 		Assert.Single(engines);
 		SliceLayouts.CreatePrimaryStackLayout(ctx, plugin, engines[0].Identity).Should().BeEquivalentTo(engines[0]);
 	}
@@ -213,7 +213,7 @@ ISliceLayoutPlugin plugin
 		// Then the layout engine is loaded
 		Assert.True(result);
 
-		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
+		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx)!;
 		Assert.Single(engines);
 		SliceLayouts
 			.CreateMultiColumnLayout(ctx, plugin, engines[0].Identity, columns)
@@ -312,7 +312,7 @@ ISliceLayoutPlugin plugin
 		// Then the layout engine is loaded
 		Assert.True(result);
 
-		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
+		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx)!;
 		Assert.Single(engines);
 		SliceLayouts
 			.CreateSecondaryPrimaryLayout(ctx, plugin, engines[0].Identity, primaryCount, secondaryCount)
@@ -365,8 +365,8 @@ public void Load_InvalidLayoutEngine(string config, bool isYaml, IContext ctx)
 		// Then the layout engine is not loaded
 		Assert.True(result);
 
-		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
-		Assert.Empty(engines);
+		ILayoutEngine[]? engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
+		Assert.Null(engines);
 		ctx.PluginManager.DidNotReceive().AddPlugin(Arg.Any<ISliceLayoutPlugin>());
 	}
 }

src/Whim.Yaml.Tests/Layouts/YamlLayoutEngineLoader_TreeLayoutEngineTests.cs

@@ -115,6 +115,31 @@ public class YamlLayoutEngineLoader_TreeLayoutEngineTests
 				false,
 				Direction.Down
 			},
+			// Use the default direction.
+			{
+				"""
+					layout_engines:
+					  entries:
+					    - type: TreeLayoutEngine
+					""",
+				true,
+				Direction.Right
+			},
+			{
+				"""
+					{
+						"layout_engines": {
+							"entries": [
+								{
+									"type": "TreeLayoutEngine"
+								}
+							]
+						}
+					}
+					""",
+				false,
+				Direction.Right
+			},
 		};
 
 	[Theory]
@@ -134,7 +159,7 @@ public void LoadTreeLayoutEngine(string yaml, bool isValid, Direction direction,
 		// Then the tree layout engine should be updated
 		Assert.True(result);
 
-		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx);
+		ILayoutEngine[] engines = YamlLoaderTestUtils.GetLayoutEngines(ctx)!;
 		Assert.Single(engines);
 		new TreeLayoutEngine(ctx, Substitute.For<ITreeLayoutPlugin>(), engines[0].Identity)
 			.Should()