Add a document detailing the layout system (#1232)

docs/docs/config.mdx

@@ -20,7 +20,7 @@ files as well: `termthemes.json`, `presets.json`, and `widgets.json`.
 :::
 
 | Key Name                           | Type     | Function                                                                                                                                                                                                                                                      |
-|----------|------|----------|
+| ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | ai:preset                          | string   | the default AI preset to use                                                                                                                                                                                                                                  |
 | ai:baseurl                         | string   | Set the AI Base Url (must be OpenAI compatible)                                                                                                                                                                                                               |
 | ai:apitoken                        | string   | your AI api token                                                                                                                                                                                                                                             |
@@ -54,7 +54,7 @@ files as well: `termthemes.json`, `presets.json`, and `widgets.json`.
 | window:opacity                     | float64  | 0-1, window opacity when `window:transparent` or `window:blur` are set                                                                                                                                                                                        |
 | window:bgcolor                     | string   | set the window background color (should be hex: #xxxxxx)                                                                                                                                                                                                      |
 | window:reducedmotion               | bool     | set to true to disable most animations                                                                                                                                                                                                                        |
-| window:tilegapsize | int | set to change override default gap between blocks |
+| window:tilegapsize                 | int      | set to change override default gap size (in CSS pixels) between blocks                                                                                                                                                                                        |
 | window:showmenubar                 | bool     | set to use the OS-native menu bar (Windows and Linux only, requires app restart)                                                                                                                                                                              |
 | window:nativetitlebar              | bool     | set to use the OS-native title bar, rather than the overlay (Windows and Linux only, requires app restart)                                                                                                                                                    |
 | window:disablehardwareacceleration | bool     | set to disable Chromium hardware acceleration to resolve graphical bugs (requires app restart)                                                                                                                                                                |
@@ -123,7 +123,7 @@ Here is an example of defining a full terminal theme.  All of the built-in theme
 ```
 
 | Key Name            | Type      | ANSI FG# | ANSI BG# | Function                                                                                                                                 |
-|----------|------|----------|----------|----------|
+| ------------------- | --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | display:name        | string    |          |          | the name as it will appear in the UI context menu                                                                                        |
 | display:order       | float     |          |          | entries in the context menu are sorted by display:order                                                                                  |
 | black               | CSS color | 30       | 40       | color for black                                                                                                                          |

docs/docs/index.mdx

@@ -26,6 +26,7 @@ References:
 - [Key Bindings](./keybindings)
 - [wsh command](./wsh)
 - [Connections](./connections)
+- [Tab Layout System](./layout)
 - [Custom Widgets](./customwidgets)
 - [Telemetry](./telemetry)
 - [FAQ](./faq)

docs/docs/layout.mdx

@@ -0,0 +1,81 @@
+---
+sidebar_position: 2
+id: "layout"
+title: "Tab Layout System"
+---
+
+import { PlatformProvider, PlatformToggleButton } from "@site/src/components/platformcontext.tsx";
+import { Kbd } from "@site/src/components/kbd.tsx";
+
+<PlatformProvider>
+<PlatformToggleButton/>
+
+![screenshot showing a block being dragged over another block, with the placeholder depicting a out-of-line before outer drop](./img/drag-edge.png)
+
+## Layout system under the hood
+
+:::info
+
+**Definitions**
+
+- Layout tree: the in-memory representation of a tab layout, comprised of nodes
+- Node: An entry in the layout tree, either a single block (a leaf) or an ordered list of nodes. Defines a tiling direction (row or column) and a unitless size
+- Block: The contents of a leaf in the layout tree, defines what contents is displayed at the given layout location
+
+:::
+
+Our layout system emulates the [CSS Flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox) system, comprising of a tree of columns and rows. Under the hood, the layout is represented as an n-tree, where each node in the tree is either a single block, or a list of nodes. Each level in the tree alternates the direction in which it tiles (level 1 tiles as a row, level 2 as a column, level 3 as a row, etc.).
+
+## Layout actions
+
+### Add a new block
+
+You can add new blocks by selecting a widget from the right sidebar.
+
+Starting at the topmost level of the tree, since the first level tiles as a row, new blocks will be added to the right side of existing blocks. Once there are 5 blocks across, new blocks will begin being added below existing blocks, starting from the right side and working to the left. As a new block gets added below an existing one, the node containing the existing block is converted from a single-block node to a list node and the existing block definition is moved one level deeper in the tree as the first element of the node list. New blocks will always be added to the last-available node in the deepest level, where available is defined as having less than five children. We don't set a limit on the number of blocks in a tab, but you may experience degraded performance past around 25 blocks.
+
+While we define a 5-child limit for each node in the tree when automatically placing new blocks, there is no actual limit to the number of children a node can hold. After the block is placed, you are free to move it wherever in the layout
+
+### Delete a block
+
+You can delete blocks by clicking the <i className="fa-sharp fa-xmark-large"/> button in the top-right corner of the block, by right-clicking on the block header and selecting "Close Block" from the context menu, or by running the [`wsh deleteblock` command](./wsh#deleteblock). Alternatively, the currently focused block/widget can be closed by pressing <Kbd k="Cmd:w"/>
+
+When you delete a block, the layout tree will be automatically adjusted to minimize the tree depth.
+
+### Move a block
+
+You can move blocks by clicking on the block header and dragging the block around the tab. You will see placeholders appear to show where the block will land when you drop it.
+
+There are 7 different drop targets for any given block. A block is divided into quadrants along its diagonals. If the block is tiling as a row (left-to-right), dropping a block into the left or right quadrant will place the dropped block in the same level as the targeted block. This can be considered dropping the block inline. If you drop the block out of line (in quadrants corresponding to opposite tiling direction), the block will either be placed one level above or one level below the targeted block. Dropping the block towards the outside will place it in the same level as the target block's parent, while dropping it towards the center of the block will create a new level, where both the target block and the dropped block will be moved. The middle fifth of the block is reserved for the swap action. Dropping a block here will cause the target block and the dropped block to swap positions in the layout.
+
+![screenshot showing a block being dragged over another block, with the placeholder depicting a swap movement](./img/drag-swap.png)
+
+#### Possible block movements
+
+:::note
+All block movements except for Swap will cause the rest of the layout to shift to accommodate the block's new displacement.
+:::
+
+![annotated example showing the drop targets within a block](./img/block-drag-example.jpg)
+
+1. Inline before: Drops the block under the same node as the target block, placing it before the target in the same tiling direction
+2. Inline after: Drops the block under the same node as the target block, placing it after the target in the same tiling direction
+3. Out-of-line before outer: Drops the block before the target block's parent node in the opposite tiling direction
+4. Out-of-line before inner: Segments the target block, creating a new node in the tree. Places the dropped block before the target block in the opposite tiling direction.
+5. Out-of-line after inner: Segments the target block, creating a new node in the tree. Places the dropped block after the target block in the opposite tiling direction.
+6. Out-of-line after outer: Drops the block after the target block's parent node in the opposite tiling direction
+7. Swap: Swaps the position of the dropped block and the targeted block in the layout, preserving the rest of the layout
+
+### Resize a block
+
+![screenshot showing the line that appears when the cursor hovers over the margin of a block, indicating which blocks will be resized by dragging the margin](./img/node-resize.png)
+
+You do not directly resize a block. Rather, you resize the nodes containing the blocks. If you hover your mouse over the margin of a block, you will see the cursor change to <i className="fa-sharp fa-arrows-left-right"/> or <i className="fa-sharp fa-arrows-up-down"/> to indicate the direction the node can be resized. You will also see a line appear after 500ms to show you how many blocks will be resized by moving that margin. Clicking and dragging on this margin will cause the block(s) to get resized.
+
+Node sizes are unitless values. The ratio of all node sizes at a given tree level determines the displacement of each node. If you move a block and its node is deleted, the other nodes at the given tree level will adjust their sizes to account for the new size ratio.
+
+## Change the gap size between blocks
+
+The gap between blocks defaults to 3px, but this value can be changed by modifying the `window:tilegapsize` configuration value. See [Configuration](./config) for more information on how to change configuration values.
+
+</PlatformProvider>

docs/docs/widgets.mdx

@@ -35,10 +35,14 @@ Magnifying a widget will pop the widget out in front of everything else. You can
 
 By dragging and dropping their headers, widgets can be moved to different locations in the layout. This effectively allows you to reorganize your screen however you see fit. When dragging, you will see a preview of the widget that is being dragged. When the widget is over a valid drop point, the area where it would be moved to will turn green. Releasing the click will place the widget there and reflow the other widgets around it. If you see a green box cover half of two different widgets, the drop will place the widget between the two. If you see the green box cover half of one widget at the edge of the screen, the widget will be placed between that widget and the edge of the screen. If you see the green box cover one widget entirely, the two widgets will swap locations.
 
+See [Tab Layout System](./layout#move-a-block) for more information.
+
 ### How to Resize Widgets
 
 Hovering the mouse between two widgets changes your cursor to <i className="fa-sharp fa-arrows-left-right"/> or <i className="fa-sharp fa-arrows-up-down"/>; and reveals a green line dividing the widgets. By dragging and dropping this green line, you are able to resize the widgets adjacent to it.
 
+See [Tab Layout System](./layout#resize-a-block) for more information.
+
 ## Types of Widgets
 
 ### Term