feat(modal_wezterm): add modal.wezterm annotations

README.md

@@ -46,6 +46,7 @@ for any unclear types.
 - [Featured Plugins](#featured-plugins)
   - [`tabline.wez`](#tablinewez)
   - [`wezterm-config.nvim`](#wezterm-confignvim)
+  - [`modal.wezterm`](#modalwezterm)
 - [License](#license)
 
 ---
@@ -186,6 +187,16 @@ as shown below:
 local wezterm_config_nvim = wezterm.plugin.require('https://github.com/winter-again/wezterm-config.nvim')
 ```
 
+### `modal.wezterm`
+
+You can import type annotations for
+[`MLFlexer/modal.wezterm`](https://github.com/MLFlexer/modal.wezterm) as shown below:
+
+```lua
+---@type ModalWezterm
+local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")
+```
+
 ---
 
 ## Collaborators

lua/wezterm/types/enum/key-assignment.lua

@@ -76,6 +76,66 @@ local copy_mode = {
 
 ---@alias SendKey Key
 
+---Activates a named key table.
+---
+---@class ActivateKeyTableParams
+---The name of the table to activate.
+---
+---The name must match up to an entry in the `config.key_tables` configuration.
+---
+---See:
+--- - [`config.key_tables`](lua://Config.key_tables)
+---
+---@field name string
+---An optional duration expressed in milliseconds. If specified, then the activation
+---will automatically expire and pop itself from the key table stack once that duration elapses.
+---
+---If omitted, this activation will not expire due to time.
+---
+---@field timeout_milliseconds? integer
+---An optional boolean that controls whether the activation will pop itself
+---after a single additional key press.
+---
+---The default if left unspecified is `true`.
+---
+---When set to `false`, pressing a key will not automatically pop the activation
+---and you will need to use either a timeout or an explicit key assignment
+---that triggers `PopKeyTable` to cancel the activation.
+---
+---@field one_shot? boolean
+---An optional boolean.
+---Defaults to `false` if unspecified.
+---
+---If set to `true` then it will behave as though `PopKeyTable` was triggered
+---before pushing this new activation on the stack.
+---This is most useful for key assignments in a table that was activated
+---with `one_shot` set to `false`.
+---
+---@field replace_current? boolean
+---An optional boolean.
+---Defaults to `false` if unspecified.
+---
+---If set to `true` then a key press that doesn't match any entries
+---in the named key table will implicitly pop this entry from the stack.
+---This can be used together with `timeout_milliseconds`.
+---
+---@field until_unknown? boolean
+---An optional boolean.
+---Defaults to `false` if unspecified.
+---
+---If set to `true` then a key press that doesn't match any entries
+---in the named key table will halt any further key table stack matching,
+---allowing only key assignments that are defined in the current key table activation to match.
+---
+---**Use with care**: If you haven't defined an explicit `PopKeyTable` assignment
+---in the key table you may lock yourself out of the keyboard
+---and will need to reload the configuration file
+---(e.g. by re-saving it) to get back in.
+---
+---@field prevent_fallback? boolean
+
+---@alias ActivateKeyTable fun(params: ActivateKeyTableParams)
+
 ---@enum (key) KeyAssignment
 local key_assignment = {
   ActivateCommandPalette = 1,
@@ -434,7 +494,7 @@ local key_assignment = {
 ---@class ActionFuncClass
 ---@field ActivateCommandPalette KeyAssignFunction
 ---@field ActivateCopyMode KeyAssignFunction
----@field ActivateKeyTable KeyAssignFunction
+---@field ActivateKeyTable ActivateKeyTable
 ---@field ActivateLastTab KeyAssignFunction
 ---@field ActivatePaneByIndex KeyAssignFunction
 ---@field ActivatePaneDirection KeyAssignFunction

lua/wezterm/types/plugins/modal_wezterm.lua

@@ -0,0 +1,70 @@
+---@meta
+---@diagnostic disable:unused-local
+
+---@alias ModalWeztermSeparator { text: string, bg: string, fg: string }
+
+---@class ModalWezterm
+---@field modes table<string, { name: string, key_table_name: string, status_text: string }>
+---@field key_tables Key[]
+local M = {}
+
+---@param window Window
+function M.get_mode(window) end
+
+---@param name string
+---@param key_table Key[]
+---@param key_table_name? string
+---@param status_text? string
+function M.add_mode(name, key_table, status_text, key_table_name) end
+
+---Wrapper for creating a simple status text.
+---
+---@param left_seperator ModalWeztermSeparator
+---@param key_hints ModalWeztermSeparator
+---@param mode ModalWeztermSeparator
+---@return string status_text
+function M.create_status_text(left_seperator, key_hints, mode) end
+
+---@param url string
+function M.enable_defaults(url) end
+
+---Sets the current modal status to the right status.
+---
+---@param window Window
+function M.set_right_status(window) end
+
+---Sets the window title by emitting a OSC 2 escape sequence.
+---@param pane Pane
+---@param name? string
+function M.set_window_title(pane, name) end
+
+---Resets the window title to the foreground process by emitting a OSC 2 escape sequence.
+---
+---@param pane Pane
+function M.reset_window_title(pane) end
+
+---Activates mode.
+---
+---@param name string
+---@param activate_key_table_params? ActivateKeyTableParams
+---@return KeyAssignment|KeyAssignFunction|ActivateKeyTable
+function M.activate_mode(name, activate_key_table_params) end
+
+---Exits active mode.
+---
+---@param name string
+---@return KeyAssignment|KeyAssignFunction
+function M.exit_mode(name) end
+
+---Exits all active modes
+---@param name string
+---@return KeyAssignment|KeyAssignFunction
+function M.exit_all_modes(name) end
+
+---@param config Config
+function M.apply_to_config(config) end
+
+---@param config Config
+function M.set_default_keys(config) end
+
+-- vim: set ts=2 sts=2 sw=2 et ai si sta: