Keymap domain facade.
Manages key bindings across editor modes, scopes, and filetypes.
Internally backed by a trie data structure (Keymap.Bindings) for
prefix-matching key sequences, and an ETS-backed GenServer
(Keymap.Active) for live binding state that merges defaults with
user overrides.
External callers use this facade for binding lookups, key resolution,
and runtime rebinding. The Keymap.Bindings trie type appears in
specs across mode dispatch and input handling code.
Server-aware API
Every binding-lookup and runtime-rebinding function takes an optional
server argument. When omitted, calls go to the singleton process
registered under the default_server/0 name. Pass an explicit server
(pid or registered name) to target an isolated instance, e.g. per-test
fixtures or future per-tab keymaps.
Summary
Functions
Binds a key sequence to a command in the given mode.
Binds a key sequence with options (e.g., filetype:).
Binds a key sequence on an explicit keymap server.
Returns all default bindings as a flat list.
Returns the default leader trie (before user overrides).
Returns the default normal-mode single-key bindings.
Returns the registered name of the default keymap server.
Returns the filetype-scoped trie (SPC m bindings).
Returns the merged leader trie (defaults + user overrides).
Returns the mode-specific trie for the given mode.
Returns the merged normal-mode single-key bindings.
Resets all bindings to defaults (discards user overrides).
Resolves a key press against a mode's merged bindings.
Resolves a key press within a scope (e.g., :editor, :agent, :file_tree).
Returns the scope-specific trie for a given scope and vim state.
Removes a key binding from a mode.
Types
@type mode() :: :normal | :insert | :visual | :command
Supported editor modes.
@type server() :: GenServer.server()
Reference to a Keymap.Active GenServer (registered name or pid).
Functions
Binds a key sequence to a command in the given mode.
@spec bind(atom() | {atom(), atom()}, String.t(), atom(), String.t(), keyword()) :: :ok | {:error, String.t()}
Binds a key sequence with options (e.g., filetype:).
@spec bind( server(), atom() | {atom(), atom()}, String.t(), atom(), String.t(), keyword() ) :: :ok | {:error, String.t()}
Binds a key sequence on an explicit keymap server.
@spec default_bindings() :: [{[Minga.Keymap.Bindings.key()], atom(), String.t()}]
Returns all default bindings as a flat list.
@spec default_leader_trie() :: Minga.Keymap.Bindings.node_t()
Returns the default leader trie (before user overrides).
@spec default_normal_bindings() :: %{ required(Minga.Keymap.Bindings.key()) => {atom(), String.t()} }
Returns the default normal-mode single-key bindings.
@spec default_server() :: server()
Returns the registered name of the default keymap server.
@spec filetype_trie(server(), atom()) :: Minga.Keymap.Bindings.node_t()
Returns the filetype-scoped trie (SPC m bindings).
@spec leader_trie(server()) :: Minga.Keymap.Bindings.node_t()
Returns the merged leader trie (defaults + user overrides).
@spec mode_trie(server(), atom()) :: Minga.Keymap.Bindings.node_t()
Returns the mode-specific trie for the given mode.
@spec normal_bindings(server()) :: %{ required(Minga.Keymap.Bindings.key()) => {atom(), String.t()} }
Returns the merged normal-mode single-key bindings.
@spec reset(server()) :: :ok
Resets all bindings to defaults (discards user overrides).
@spec resolve_binding(server(), atom(), atom() | nil, Minga.Keymap.Bindings.key()) :: {:command, atom()} | :not_found
Resolves a key press against a mode's merged bindings.
Checks mode-specific trie first, then normal overrides.
Returns {:command, atom()} when a command is found, or :not_found.
@spec resolve_scoped_key( Minga.Keymap.Scope.scope_name(), Minga.Keymap.Scope.vim_state(), Minga.Keymap.Bindings.key(), keyword() ) :: Minga.Keymap.Scope.resolve_result()
Resolves a key press within a scope (e.g., :editor, :agent, :file_tree).
Checks scope-specific bindings first, then falls through to the
scope's fallback chain. Returns Scope.resolve_result():
{:command, atom()}, {:prefix, Bindings.node_t()}, or :not_found.
@spec scope_trie( server(), Minga.Keymap.Scope.scope_name(), Minga.Keymap.Scope.vim_state() ) :: Minga.Keymap.Bindings.node_t()
Returns the scope-specific trie for a given scope and vim state.
Removes a key binding from a mode.