docs for PaneSelect

refs: #1975
refs: #1842

docs/changelog.md

@@ -39,6 +39,7 @@ As features stabilize some brief notes about them will accumulate here.
 * [ime_preedit_rendering](config/lua/config/ime_preedit_rendering.md) option to choose whether to use the builtin or the system IME preedit rendering mode. Thanks to [@kumattau](https://github.com/kumattau)! [#2006](https://github.com/wez/wezterm/pull/2006)
 * [wezterm.strftime_utc](config/lua/wezterm/strftime_utc.md) for manipulating times in UTC rather than the local timezone
 * `wezterm cli send-text --no-paste` option to send text to a pain without wrapping it as a bracketed paste
+* [PaneSelect](config/lua/keyassignment/PaneSelect.md) key assignment to activate the pane selection UI to activate or swap the selected pane. [#1842](https://github.com/wez/wezterm/issues/1842) [#1975](https://github.com/wez/wezterm/issues/1975)
 
 #### Updated
 * Bundled harfbuzz to 4.3.0

docs/config/lua/keyassignment/PaneSelect.md

@@ -0,0 +1,38 @@
+# PaneSelect
+
+*Since: nightly builds only*
+
+This action activates the pane selection modal display. In this mode, each pane
+will be overlayed with a one- or two-character label taken from the selection
+alphabet.
+
+Typing the label will select the pane, take an action and exit selection mode.
+Pressing `Escape` or `CTRL-g` will exit pane selection mode without taking any
+action.
+
+The available actions are:
+
+* `mode="Activate"` - activate the selected pane. This is the default mode.
+* `mode="SwapWithActive"` - swap the position of the active pane with the selected pane
+
+The selection alphabet defaults to the same value as [quick_select_alphabet](../config/quick_select_alphabet.md), but can be explicitly via the `alphabet` field:
+
+```lua
+local wezterm = require 'wezterm'
+
+return {
+  -- 36 is the default, but you can choose a different size
+  -- pane_select_font_size=36,
+
+  keys = {
+    -- activate pane selection mode with the default alphabet (labels are "a", "s", "d", "f" and so on)
+    {key="8", mods="CTRL", action=wezterm.action{PaneSelect={}}},
+    -- activate pane selection mode with numeric labels
+    {key="9", mods="CTRL", action=wezterm.action{PaneSelect={alphabet="1234567890"}}},
+    -- show the pane selection mode, but have it swap the active and selected panes
+    {key="0", mods="CTRL", action=wezterm.action{PaneSelect={mode="SwapWithActive"}}},
+  }
+}
+```
+
+See also [RotatePanes](RotatePanes.md).

docs/config/lua/keyassignment/RotatePanes.md

@@ -48,3 +48,4 @@ return {
 }
 ```
 
+See also [PaneSelect](PaneSelect.md).