--- *mini.clue* Show next key clues

---

--- MIT License Copyright (c) 2023 Evgeni Chasnovski

--- Features:

--- - Implement custom key query process to reach target key combination:

--- - Starts after customizable opt-in triggers (mode + keys).

---

--- - Each key press narrows down set of possible targets.

--- Pressing `<BS>` removes previous user entry.

--- Pressing `<Esc>` or `<C-c>` leads to an early stop.

--- Doesn't depend on 'timeoutlen' and has basic support for 'langmap'.

---

--- - Ends when there is at most one target left or user pressed `<CR>`.

--- Results into emulating pressing all query keys plus possible postkeys.

---

--- - Show window (after configurable delay) with clues. It lists available

--- next keys along with their descriptions (auto generated from descriptions

--- present keymaps and user-supplied clues; preferring the former).

---

--- - Configurable "postkeys" for key combinations - keys which will be emulated

--- after combination is reached during key query process.

---

--- - Provide customizable sets of clues for common built-in keys/concepts:

--- - `g` key.

--- - `z` key.

--- - Window commands.

--- - Built-in completion.

--- - Marks.

--- - Registers.

---

--- - Lua functions to disable/enable triggers globally or per buffer.

---

--- For more details see:

--- - |MiniClue-key-query-process|.

--- - |MiniClue-examples|.

--- - |MiniClue.config|.

--- - |MiniClue.gen_clues|.

---

--- Notes:

--- - There is no functionality to create mappings while defining clues.

--- This is done to clearly separate these two different actions.

--- The best suggested practice is to manually create mappings with

--- descriptions (`desc` field in options), as they will be automatically

--- used inside clue window.

---

--- - Triggers are implemented as special buffer-local mappings. This leads to

--- several caveats:

--- - They will override same regular buffer-local mappings and have

--- precedence over global one.

---

--- Example: having set `<C-w>` as Normal mode trigger means that

--- there should not be another `<C-w>` mapping.

---

--- - They need to be the latest created buffer-local mappings or they will

--- not function properly. Most common indicator of this is that some

--- mapping starts to work only after clue window is shown.

---

--- Example: `g` is set as Normal mode trigger, but `gcc` from |mini.comment|

--- doesn't work right away. This is probably because there are some

--- other buffer-local mappings starting with `g` which were created after

--- mapping for `g` trigger. Most common places for this are in LSP server's

--- `on_attach` or during tree-sitter start in buffer.

---

--- To check if trigger is the most recent buffer-local mapping, execute

--- `:<mode-char>map <trigger-keys>` (like `:nmap g` for previous example).

--- Mapping for trigger should be the first listed.

---

--- This module makes the best effort to work out of the box and cover

--- most common cases, but it is not foolproof. The solution here is to

--- ensure that triggers are created after making all buffer-local mappings:

--- run either |MiniClue.setup()| or |MiniClue.ensure_buf_triggers()|.

---

--- - Descriptions from existing mappings take precedence over user-supplied

--- clues. This is to ensure that information shown in clue window is as

--- relevant as possible. To add/customize description of an already existing

--- mapping, use |MiniClue.set_mapping_desc()|.

---

--- - Due to technical difficulties, there is no foolproof support for

--- Operator-pending mode triggers (like `a`/`i` from |mini.ai|):

--- - Doesn't work as part of a command in "temporary Normal mode" (like

--- after |i_CTRL-O|) due to implementation difficulties.

--- - Can have unexpected behavior with custom operators.

---

--- - Has (mostly solved) issues with macros:

--- - All triggers are disabled during macro recording due to technical

--- reasons.

--- - The `@` and `Q` keys are specially mapped inside |MiniClue.setup()|

--- (if the key is not already mapped) to temporarily disable triggers.

---

--- # Setup ~

---

--- This module needs a setup with `require('mini.clue').setup({})` (replace

--- `{}` with your `config` table). It will create global Lua table `MiniClue`

--- which you can use for scripting or manually (with `:lua MiniClue.*`).

---

--- Config table **needs to have triggers configured**, none is set up by default.

---

--- See |MiniClue.config| for available config settings.

---

--- You can override runtime config settings (like clues or window options)

--- locally to a buffer inside `vim.b.miniclue_config` which should have same

--- structure as `MiniClue.config`. See |mini.nvim-buffer-local-config| for

--- more details.

---

--- # Comparisons ~

---

--- - [folke/which-key.nvim](https://github.com/folke/which-key.nvim):

--- - Both have the same main goal: show available next keys along with

--- their customizable descriptions.

--- - Has different UI and content layout.

--- - Allows creating mappings inside its configuration, while this module

--- doesn't have this by design (to clearly separate two different tasks).

--- - Doesn't allow creating submodes, while this module does (via `postkeys`).

---

--- - [anuvyklack/hydra.nvim](https://github.com/anuvyklack/hydra.nvim):

--- - Both allow creating submodes: state which starts at certain key

--- combination; treats some keys differently; ends after `<Esc>`.

--- - Doesn't show information about available next keys (outside of

--- submodes), while that is this module's main goal.

---

--- # Highlight groups ~

---

--- - `MiniClueBorder` - window border.

--- - `MiniClueDescGroup` - group description in clue window.

--- - `MiniClueDescSingle` - single target description in clue window.

--- - `MiniClueNextKey` - next key label in clue window.

--- - `MiniClueNextKeyWithPostkeys` - next key label with postkeys in clue window.

--- - `MiniClueSeparator` - separator in clue window.

--- - `MiniClueTitle` - window title.

---

--- To change any highlight group, set it directly with |nvim_set_hl()|.

---

--- # Disabling ~

---

--- To disable creating triggers, set `vim.g.miniclue_disable` (globally) or

--- `vim.b.miniclue_disable` (for a buffer) to `true`. Considering high number

--- of different scenarios and customization intentions, writing exact rules

--- for disabling module's functionality is left to user. See

--- |mini.nvim-disabling-recipes| for common recipes.

---@tag MiniClue

--- # General info ~

---

--- This module implements custom key query process imitating a usual built-in

--- mechanism of user pressing keys in order to execute a mapping. General idea

--- is the same: narrow down key combinations until the target is reached.

---

--- Main goals of its existence are:

---

--- - Allow reaching certain mappings be independent of 'timeoutlen'. That is,

--- there is no fixed timeout after which currently typed keys are executed.

---

--- - Enable automated showing of next key clues after user-supplied delay

--- (also independent of 'timeoutlen').

---

--- - Allow emulating configurable key presses after certain key combination is

--- reached. This granular control allows creating so called "submodes".

--- See more at |MiniClue-examples-submodes|.

---

--- This process is primarily designed for nested `<Leader>` mappings in Normal

--- mode but works in all other main modes: Visual, Insert, Operator-pending

--- (with caveats; no foolproof guarantees), Command-line, Terminal.

---

--- # Lifecycle ~

---

--- - Key query process starts when user types a trigger: certain keys in certain

--- mode. Those keys are put into key query as a single user input. All possible

--- mode key combinations are filtered to ones starting with the trigger keys.

---

--- Note: trigger is implemented as a regular mapping, so if it has at least

--- two keys, they should be pressed within 'timeoutlen' milliseconds.

---

--- - Wait (indefinitely) for user to press a key. Advance depending on the key:

---

--- - Special key:

---

--- - If `<Esc>` or `<C-c>`, stop the process without any action.

---

--- - If `<CR>`, stop the process and execute current key query, meaning

--- emulate (with |nvim_feedkeys()|) user pressing those keys.

---

--- - If `<BS>`, remove previous user input from the query. If query becomes

--- empty, stop the process without any action.

---

--- - If a key for scrolling clue window (`scroll_down` / `scroll_up`

--- in `config.window`; `<C-d>` / `<C-u>` by default), scroll clue window

--- and wait for the next user key.

--- Note: if clue window is not shown, treated as a not special key.

---

--- - Not special key. Add key to the query while filtering all available

--- key combinations to start with the current key query. Advance:

---

--- - If there is a single available key combination matching current

--- key query, execute it.

---

--- - If there is no key combinations starting with the current query,

--- execute it. This, for instance, allows a seamless execution of

--- operators in presence of a longer key combinations. Example: with

--- `g` as trigger in Normal mode and available mappings `gc` / `gcc`

--- (like from |mini.comment|), this allows typing `gcip` to comment

--- current paragraph, although there are no key combinations

--- starting with `gci`.

---

--- - Otherwise wait for the new user key press.

---

--- # Clue window ~

---

--- After initiating key query process and after each key press, a timer is

--- started to show a clue window: floating window with information about

--- available next keys along with their descriptions. Note: if window is

--- already shown, its content is updated right away.

---

--- Clues can have these types:

---

--- - "Terminal next key": when pressed, will lead to query execution.

---

--- - "Terminal next key with postkeys": when pressed, will lead to query

--- execution plus some configured postkeys.

---

--- - "Group next key": when pressed, will narrow down available key combinations

--- and wait for another key press. Note: can have configured description

--- (inside `config.clues`) or it will be auto generated based on the number of

--- available key combinations.

---@tag MiniClue-key-query-process

--- # Full starter example ~

---

--- If not sure where to start, try this example with all provided clues from

--- this module plus all |<Leader>| mappings in Normal and Visual modes: >lua

---

--- local miniclue = require('mini.clue')

--- miniclue.setup({

--- triggers = {

--- -- Leader triggers

--- { mode = { 'n', 'x' }, keys = '<Leader>' },

---

--- -- `[` and `]` keys

--- { mode = 'n', keys = '[' },

--- { mode = 'n', keys = ']' },

---

--- -- Built-in completion

--- { mode = 'i', keys = '<C-x>' },

---

--- -- `g` key

--- { mode = { 'n', 'x' }, keys = 'g' },

---

--- -- Marks

--- { mode = { 'n', 'x' }, keys = "'" },

--- { mode = { 'n', 'x' }, keys = '`' },

---

--- -- Registers

--- { mode = { 'n', 'x' }, keys = '"' },

--- { mode = { 'i', 'c' }, keys = '<C-r>' },

---

--- -- Window commands

--- { mode = 'n', keys = '<C-w>' },

---

--- -- `z` key

--- { mode = { 'n', 'x' }, keys = 'z' },

--- },

---

--- clues = {

--- -- Enhance this by adding descriptions for <Leader> mapping groups

--- miniclue.gen_clues.square_brackets(),

--- miniclue.gen_clues.builtin_completion(),

--- miniclue.gen_clues.g(),

--- miniclue.gen_clues.marks(),

--- miniclue.gen_clues.registers(),

--- miniclue.gen_clues.windows(),

--- miniclue.gen_clues.z(),

--- },

--- })

--- <

--- # Leader clues ~

---

--- Assume there are these |<Leader>| mappings set up: >lua

---

--- -- Set `<Leader>` before making any mappings and configuring 'mini.clue'

--- vim.g.mapleader = ' '

---

--- local nmap_leader = function(suffix, rhs, desc)

--- vim.keymap.set('n', '<Leader>' .. suffix, rhs, { desc = desc })

--- end

--- local xmap_leader = function(suffix, rhs, desc)

--- vim.keymap.set('x', '<Leader>' .. suffix, rhs, { desc = desc })

--- end

---

--- nmap_leader('bd', '<Cmd>lua MiniBufremove.delete()<CR>', 'Delete')

--- nmap_leader('bw', '<Cmd>lua MiniBufremove.wipeout()<CR>', 'Wipeout')

---

--- nmap_leader('lf', '<Cmd>lua vim.lsp.buf.format()<CR>', 'Format')

--- xmap_leader('lf', '<Cmd>lua vim.lsp.buf.format()<CR>', 'Format')

--- nmap_leader('lr', '<Cmd>lua vim.lsp.buf.rename()<CR>', 'Rename')

--- nmap_leader('lR', '<Cmd>lua vim.lsp.buf.references()<CR>', 'References')

--- <

--- The following setup will enable |<Leader>| as trigger in Normal and Visual

--- modes and add descriptions to mapping groups: >lua

---

--- require('mini.clue').setup({

--- -- Register `<Leader>` as trigger

--- triggers = {

--- { mode = { 'n', 'x' }, keys = '<Leader>' },

--- },

---

--- -- Add descriptions for mapping groups

--- clues = {

--- { mode = 'n', keys = '<Leader>b', desc = '+Buffers' },

--- { mode = 'n', keys = '<Leader>l', desc = '+LSP' },

--- },

--- })

--- <

--- # Clues without mappings ~

---

--- Clues can be shown not only for actually present mappings. This is helpful for

--- showing clues for built-in key combinations. Here is an example of clues for

--- a subset of built-in completion (see |MiniClue.gen_clues.builtin_completion()|

--- to generate clues for all available completion sources): >lua

---

--- require('mini.clue').setup({

--- -- Make `<C-x>` a trigger. Otherwise, key query process won't start.

--- triggers = {

--- { mode = 'i', keys = '<C-x>' },

--- },

---

--- -- Register custom clues

--- clues = {

--- { mode = 'i', keys = '<C-x><C-f>', desc = 'File names' },

--- { mode = 'i', keys = '<C-x><C-l>', desc = 'Whole lines' },

--- { mode = 'i', keys = '<C-x><C-o>', desc = 'Omni completion' },

--- { mode = 'i', keys = '<C-x><C-s>', desc = 'Spelling suggestions' },

--- { mode = 'i', keys = '<C-x><C-u>', desc = "With 'completefunc'" },

--- }

--- })

--- <

--- # Triggers in special buffers ~

---

--- By default triggers are automatically created in listed ('buflisted') and some

--- special non-listed buffers. Use |MiniClue.ensure_buf_triggers()| to manually

--- enable in when you need them. For example: >vim

---

--- au FileType special_ft lua MiniClue.ensure_buf_triggers()

--- <

--- # Submodes ~

--- *MiniClue-examples-submodes*

---

--- Submode is a state initiated after pressing certain key combination ("prefix")

--- during which some keys are interpreted differently.

---

--- In this module submode can be implemented following these steps:

---

--- - Create mappings for each key inside submode. Left hand side of mappings

--- should consist from prefix followed by the key.

---

--- - Create clue for each key inside submode with `postkeys` value equal to

--- prefix. It would mean that after executing particular key combination from

--- this submode, pressing its prefix will be automatically emulated (leading

--- back to being inside submode).

---

--- - Register submode prefix (or some of its starting part) as trigger. Do not

--- register "overlapping" triggers, like `<Leader>` and `<Leader>m`.

---

--- ## Submode examples ~

---

--- - Submode for moving with |mini.move|:

--- - Press `<Leader>m` to start submode.

--- - Press any of `h`/`j`/`k`/`l` to move selection/line.

--- - Press `<Esc>` to stop submode.

---

--- The code: >lua

---

--- require('mini.move').setup({

--- mappings = {

--- left = '<Leader>mh',

--- right = '<Leader>ml',

--- down = '<Leader>mj',

--- up = '<Leader>mk',

--- line_left = '<Leader>mh',

--- line_right = '<Leader>ml',

--- line_down = '<Leader>mj',

--- line_up = '<Leader>mk',

--- },

--- })

---

--- require('mini.clue').setup({

--- triggers = {

--- -- This can also set up directly `<Leader>m` as a trigger, but make

--- -- sure to not also use `<Leader>`, as they would "overlap"

--- { mode = { 'n', 'x' }, keys = '<Leader>' },

--- },

--- clues = {

--- { mode = 'n', keys = '<Leader>m', desc = '+Move' },

---

--- { mode = { 'n', 'x' }, keys = '<Leader>mh', postkeys = '<Leader>m' },

--- { mode = { 'n', 'x' }, keys = '<Leader>mj', postkeys = '<Leader>m' },

--- { mode = { 'n', 'x' }, keys = '<Leader>mk', postkeys = '<Leader>m' },

--- { mode = { 'n', 'x' }, keys = '<Leader>ml', postkeys = '<Leader>m' },

--- },

--- })

--- <

--- - Submode for iterating buffers and windows with |mini.bracketed|:

--- - Press `[` or `]` to start key query process for certain direction.

--- - Press `b` / `w` to iterate buffers/windows until reach target one.

--- - Press `<Esc>` to stop submode.

---

--- The code: >lua

---

--- require('mini.bracketed').setup()

---

--- require('mini.clue').setup({

--- triggers = {

--- { mode = 'n', keys = ']' },

--- { mode = 'n', keys = '[' },

--- },

--- clues = {

--- { mode = 'n', keys = ']b', postkeys = ']' },

--- { mode = 'n', keys = ']w', postkeys = ']' },

---

--- { mode = 'n', keys = '[b', postkeys = '[' },

--- { mode = 'n', keys = '[w', postkeys = '[' },

--- },

--- })

--- <

--- - Submode for window commands using |MiniClue.gen_clues.windows()|:

--- - Press `<C-w>` to start key query process.

--- - Press keys which move / change focus / resize windows.

--- - Press `<Esc>` to stop submode.

---

--- The code: >lua

---

--- local miniclue = require('mini.clue')

--- miniclue.setup({

--- triggers = {

--- { mode = 'n', keys = '<C-w>' },

--- },

--- clues = {

--- miniclue.gen_clues.windows({

--- submode_move = true,

--- submode_navigate = true,

--- submode_resize = true,

--- })

--- },

--- })

--- <

--- # Window config ~

--- >lua

--- require('mini.clue').setup({

--- triggers = { { mode = 'n', keys = '<Leader>' } },

---

--- window = {

--- -- Show window immediately

--- delay = 0,

---

--- config = {

--- -- Compute window width automatically

--- width = 'auto',

---

--- -- Use double-line border

--- border = 'double',

--- },

--- },

--- })

--- <

---@tag MiniClue-examples

---@diagnostic disable:undefined-field

---@diagnostic disable:discard-returns

---@diagnostic disable:unused-local

---@diagnostic disable:cast-local-type

-- Module definition ==========================================================

local MiniClue = {}

local H = {}

--- Module setup

---

---@param config table|nil Module config table. See |MiniClue.config|.

---

---@usage >lua

--- require('mini.clue').setup({}) -- replace {} with your config table

--- -- needs `triggers` field present

--- <

MiniClue.setup = function(config)

-- Export module

_G.MiniClue = MiniClue

-- Setup config

config = H.setup_config(config)

-- Apply config

H.apply_config(config)

-- Define behavior

H.create_autocommands()

-- Create default highlighting

H.create_default_hl()

end

--stylua: ignore

--- Defaults ~

---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)

---@text # General info ~

---

--- - To use |<Leader>| as part of the config (either as trigger or inside clues),

--- set it prior to running |MiniClue.setup()|.

---

--- - See |MiniClue-examples| for examples.

---

--- # Clues ~

---

--- `config.clues` is an array with extra information about key combinations.

--- Each element can be one of:

--- - Clue table.

--- - Array (possibly nested) of clue tables.

--- - Callable (function) returning either of the previous two.

---

--- A clue table is a table with the following fields:

--- - <mode> `(string|table)` - single character describing mode short-name of

--- key combination as in `nvim_set_keymap()` ('n', 'x', 'i', 'o', 'c', etc.),

--- or a array thereof.

--- - <keys> `(string)` - key combination for which clue will be shown.

--- "Human-readable" key names as in |key-notation| (like "<Leader>", "<Space>",

--- "<Tab>", etc.) are allowed.

--- - <desc> `(string|function|nil)` - optional key combination description which is

--- shown in clue window. If function, should return string description.

--- - <postkeys> `(string|nil)` - optional postkeys which will be executed

--- automatically after `keys`. Allows creation of submodes

--- (see |MiniClue-examples-submodes|).

---

--- Notes:

--- - Postkeys are literal simulation of keypresses with |nvim_feedkeys()|.

---

--- - Suggested approach to configuring clues is to create mappings with `desc`

--- field while supplying to `config.clues` only elements describing groups,

--- postkeys, and built-in mappings.

---

--- # Triggers ~

---

--- `config.triggers` is an array with information when |MiniClue-key-query-process|

--- should start. Each element is a trigger table with the fields <mode> and

--- <keys> which are treated the same as in clue table.

---

--- # Window ~

---

--- `config.window` defines behavior of clue window.

---

--- `config.window.delay` is a number of milliseconds after which clue window will

--- appear. Can be 0 to show immediately.

---

--- `config.window.config` is a table defining floating window characteristics

--- or a callable returning such table (will be called with identifier of

--- window's buffer already showing all clues). It should have the same

--- structure as in |nvim_open_win()| with the following enhancements:

--- - <width> field can be equal to `"auto"` leading to window width being

--- computed automatically based on its content. Default is fixed width of 30.

--- - <row> and <col> can be equal to `"auto"` in which case they will be

--- computed to "stick" to set anchor ("SE" by default; see |nvim_open_win()|).

--- This allows changing corner in which window is shown: >lua

---

--- -- Pick one anchor

--- local anchor = 'NW' -- top-left

--- local anchor = 'NE' -- top-right

--- local anchor = 'SW' -- bottom-left

--- local anchor = 'SE' -- bottom-right

---

--- require('mini.clue').setup({

--- window = {

--- config = { anchor = anchor, row = 'auto', col = 'auto' },

--- },

--- })

--- <

--- `config.window.scroll_down` / `config.window.scroll_up` are strings defining

--- keys which will scroll clue window down / up which is useful in case not

--- all clues fit in current window height. Set to empty string `''` to disable

--- either of them.

MiniClue.config = {

-- Array of extra clues to show

clues = {},

-- Array of opt-in triggers which start custom key query process.

-- **Needs to have something in order to show clues**.

triggers = {},

-- Clue window settings

window = {

-- Floating window config

config = {},

-- Delay before showing clue window

delay = 1000,

-- Keys to scroll inside the clue window

scroll_down = '<C-d>',

scroll_up = '<C-u>',

},

}

--minidoc_afterlines_end

--- Enable triggers in all listed and some special buffers

MiniClue.enable_all_triggers = function()

for _, buf_id in ipairs(vim.api.nvim_list_bufs()) do

-- Map only inside valid listed buffers and ones with special filetypes

local is_special = H.ft_to_enable[vim.bo[buf_id].filetype]

if vim.fn.buflisted(buf_id) == 1 or is_special then H.map_buf_triggers(buf_id) end

end

end

--- Enable triggers in buffer

---

---@param buf_id number|nil Buffer identifier. Default: current buffer.

MiniClue.enable_buf_triggers = function(buf_id)

buf_id = (buf_id == nil or buf_id == 0) and vim.api.nvim_get_current_buf() or buf_id

if not H.is_valid_buf(buf_id) then H.error('`buf_id` should be a valid buffer identifier.') end

H.map_buf_triggers(buf_id)

end

--- Disable triggers in all buffers

MiniClue.disable_all_triggers = function()

for _, buf_id in ipairs(vim.api.nvim_list_bufs()) do

H.unmap_buf_triggers(buf_id)

end

end

--- Disable triggers in buffer

---

---@param buf_id number|nil Buffer identifier. Default: current buffer.

MiniClue.disable_buf_triggers = function(buf_id)

buf_id = (buf_id == nil or buf_id == 0) and vim.api.nvim_get_current_buf() or buf_id

if not H.is_valid_buf(buf_id) then H.error('`buf_id` should be a valid buffer identifier.') end

H.unmap_buf_triggers(buf_id)

end

--- Ensure all triggers are valid

MiniClue.ensure_all_triggers = function()

MiniClue.disable_all_triggers()

MiniClue.enable_all_triggers()

end

--- Ensure buffer triggers are valid

---

---@param buf_id number|nil Buffer identifier. Default: current buffer.

MiniClue.ensure_buf_triggers = function(buf_id)

MiniClue.disable_buf_triggers(buf_id)

MiniClue.enable_buf_triggers(buf_id)

end

--- Update description of an existing mapping

---

--- Notes:

--- - Uses buffer-local mapping in case there are both global and buffer-local

--- mappings with same mode and LHS. Similar to |maparg()|.

---

---@param mode string Mapping mode (as in `maparg()`).

---@param lhs string Mapping left hand side (as `name` in `maparg()`).

---@param desc string New description to set.

MiniClue.set_mapping_desc = function(mode, lhs, desc)

if type(mode) ~= 'string' then H.error('`mode` should be string.') end

if type(lhs) ~= 'string' then H.error('`lhs` should be string.') end

if type(desc) ~= 'string' then H.error('`desc` should be string.') end

local ok_get, map_data = pcall(vim.fn.maparg, lhs, mode, false, true)

if not ok_get or vim.tbl_count(map_data) == 0 then

local msg = string.format('No mapping found for mode %s and LHS %s.', vim.inspect(mode), vim.inspect(lhs))

H.error(msg)

end

map_data.desc = desc

local ok_set = pcall(vim.fn.mapset, mode, false, map_data)

if not ok_set then H.error(vim.inspect(desc) .. ' is not a valid description.') end

end

--- Generate pre-configured clues

---

--- This is a table with function elements. Call to actually get array of clues.

MiniClue.gen_clues = {}

--- Generate clues for built-in completion

---

--- Contains clues for the following triggers: >lua

---

--- { mode = 'i', keys = '<C-x>' }

--- <

---@return table Array of clues.

MiniClue.gen_clues.builtin_completion = function()

--stylua: ignore

return {

{ mode = 'i', keys = '<C-x><C-d>', desc = 'Defined identifiers' },

{ mode = 'i', keys = '<C-x><C-e>', desc = 'Scroll up' },

{ mode = 'i', keys = '<C-x><C-f>', desc = 'File names' },

{ mode = 'i', keys = '<C-x><C-i>', desc = 'Identifiers' },

{ mode = 'i', keys = '<C-x><C-k>', desc = 'Identifiers from dictionary' },

{ mode = 'i', keys = '<C-x><C-l>', desc = 'Whole lines' },

{ mode = 'i', keys = '<C-x><C-n>', desc = 'Next completion' },

{ mode = 'i', keys = '<C-x><C-o>', desc = 'Omni completion' },

{ mode = 'i', keys = '<C-x><C-p>', desc = 'Previous completion' },

{ mode = 'i', keys = '<C-x><C-s>', desc = 'Spelling suggestions' },

{ mode = 'i', keys = '<C-x><C-t>', desc = 'Identifiers from thesaurus' },

{ mode = 'i', keys = '<C-x><C-y>', desc = 'Scroll down' },

{ mode = 'i', keys = '<C-x><C-u>', desc = "With 'completefunc'" },

{ mode = 'i', keys = '<C-x><C-v>', desc = 'Like in command line' },

{ mode = 'i', keys = '<C-x><C-z>', desc = 'Stop completion' },

{ mode = 'i', keys = '<C-x><C-]>', desc = 'Tags' },

{ mode = 'i', keys = '<C-x>s', desc = 'Spelling suggestions' },

}

end

--- Generate clues for `g` key

---

--- Contains clues for the following triggers: >lua

---

--- { mode = { 'n', 'x' }, keys = 'g' }

--- <

---@return table Array of clues.

MiniClue.gen_clues.g = function()

local gr_clue = vim.fn.has('nvim-0.11') == 1 and { mode = 'n', keys = 'gr', desc = '+LSP' }

or { mode = 'n', keys = 'gr', desc = 'Virtual replace with character' }

local gr_clue_viz = vim.fn.has('nvim-0.11') == 1 and { mode = 'x', keys = 'gr', desc = '+LSP' } or {}

--stylua: ignore

return {

{ mode = 'n', keys = 'g0', desc = 'Go to leftmost visible column' },

{ mode = 'n', keys = 'g8', desc = 'Print hex value of char under cursor' },

{ mode = 'n', keys = 'ga', desc = 'Print ascii value' },

{ mode = 'n', keys = 'gD', desc = 'Go to definition in file' },

{ mode = 'n', keys = 'gd', desc = 'Go to definition in function' },

{ mode = 'n', keys = 'gE', desc = 'Go backwards to end of previous WORD' },

{ mode = 'n', keys = 'ge', desc = 'Go backwards to end of previous word' },

{ mode = 'n', keys = 'gF', desc = 'Edit file under cursor + jump line' },

{ mode = 'n', keys = 'gf', desc = 'Edit file under cursor' },

{ mode = 'n', keys = 'gg', desc = 'Go to line (def: first)' },

{ mode = 'n', keys = 'gH', desc = 'Start Select line mode' },

{ mode = 'n', keys = 'gh', desc = 'Start Select mode' },

{ mode = 'n', keys = 'gI', desc = 'Start Insert at column 1' },

{ mode = 'n', keys = 'gi', desc = 'Start Insert where it stopped' },

{ mode = 'n', keys = 'gJ', desc = 'Join lines without extra spaces' },

{ mode = 'n', keys = 'gj', desc = 'Go down by screen lines' },

{ mode = 'n', keys = 'gk', desc = 'Go up by screen lines' },

{ mode = 'n', keys = 'gM', desc = 'Go to middle of text line' },

{ mode = 'n', keys = 'gm', desc = 'Go to middle of screen line' },

{ mode = 'n', keys = 'gN', desc = 'Select previous search match' },

{ mode = 'n', keys = 'gn', desc = 'Select next search match' },

{ mode = 'n', keys = 'go', desc = 'Go to byte' },

{ mode = 'n', keys = 'gP', desc = 'Put text before cursor + stay after it' },

{ mode = 'n', keys = 'gp', desc = 'Put text after cursor + stay after it' },

{ mode = 'n', keys = 'gQ', desc = 'Switch to "Ex" mode' },

{ mode = 'n', keys = 'gq', desc = 'Format text (operator)' },

{ mode = 'n', keys = 'gR', desc = 'Enter Virtual Replace mode' },

gr_clue,

{ mode = 'n', keys = 'gs', desc = 'Sleep' },

{ mode = 'n', keys = 'gT', desc = 'Go to previous tabpage' },

{ mode = 'n', keys = 'gt', desc = 'Go to next tabpage' },

{ mode = 'n', keys = 'gU', desc = 'Make uppercase (operator)' },

{ mode = 'n', keys = 'gu', desc = 'Make lowercase (operator)' },

{ mode = 'n', keys = 'gV', desc = 'Avoid reselect' },

{ mode = 'n', keys = 'gv', desc = 'Reselect previous Visual area' },

{ mode = 'n', keys = 'gw', desc = 'Format text + keep cursor (operator)' },

{ mode = 'n', keys = 'gx', desc = 'Execute app for file under cursor' },

{ mode = 'n', keys = 'g<C-]>', desc = '`:tjump` to tag under cursor' },

{ mode = 'n', keys = 'g<C-a>', desc = 'Dump a memory profile' },

{ mode = 'n', keys = 'g<C-g>', desc = 'Show information about cursor' },

{ mode = 'n', keys = 'g<C-h>', desc = 'Start Select block mode' },

{ mode = 'n', keys = 'g<Tab>', desc = 'Go to last accessed tabpage' },

{ mode = 'n', keys = "g'", desc = "Jump to mark (don't affect jumplist)" },

{ mode = 'n', keys = 'g#', desc = 'Search backwards word under cursor' },

{ mode = 'n', keys = 'g$', desc = 'Go to rightmost visible column' },

{ mode = 'n', keys = 'g%', desc = 'Cycle through matching groups' },

{ mode = 'n', keys = 'g&', desc = 'Repeat last `:s` on all lines' },

{ mode = 'n', keys = 'g*', desc = 'Search word under cursor' },

{ mode = 'n', keys = 'g+', desc = 'Go to newer text state' },

{ mode = 'n', keys = 'g,', desc = 'Go to newer position in change list' },

{ mode = 'n', keys = 'g-', desc = 'Go to older text state' },

{ mode = 'n', keys = 'g;', desc = 'Go to older position in change list' },

{ mode = 'n', keys = 'g<', desc = 'Display previous command output' },

{ mode = 'n', keys = 'g?', desc = 'Rot13 encode (operator)' },

{ mode = 'n', keys = 'g@', desc = "Call 'operatorfunc' (operator)" },

{ mode = 'n', keys = 'g]', desc = '`:tselect` tag under cursor' },

{ mode = 'n', keys = 'g^', desc = 'Go to leftmost visible non-whitespace' },

{ mode = 'n', keys = 'g_', desc = 'Go to lower line' },

{ mode = 'n', keys = 'g`', desc = "Jump to mark (don't affect jumplist)" },

{ mode = 'n', keys = 'g~', desc = 'Swap case (operator)' },

{ mode = 'x', keys = 'gf', desc = 'Edit selected file' },

{ mode = 'x', keys = 'gJ', desc = 'Join selected lines without extra spaces' },

{ mode = 'x', keys = 'gq', desc = 'Format selection' },

gr_clue_viz,

{ mode = 'x', keys = 'gV', desc = 'Avoid reselect' },

{ mode = 'x', keys = 'gw', desc = 'Format selection + keep cursor' },

{ mode = 'x', keys = 'g<C-]>', desc = '`:tjump` to selected tag' },

{ mode = 'x', keys = 'g<C-a>', desc = 'Increment with compound' },

{ mode = 'x', keys = 'g<C-g>', desc = 'Show information about selection' },

{ mode = 'x', keys = 'g<C-x>', desc = 'Decrement with compound' },

{ mode = 'x', keys = 'g]', desc = '`:tselect` selected tag' },

{ mode = 'x', keys = 'g?', desc = 'Rot13 encode selection' },

}

end

--- Generate clues for `[` and `]` keys

---

--- Contains clues for the following triggers: >lua

---

--- { mode = 'n', keys = '[' }

--- { mode = 'n', keys = ']' }

--- <

---@return table Array of clues.

MiniClue.gen_clues.square_brackets = function()

--stylua: ignore

return {

{ mode = 'n', keys = '[<C-D>', desc = 'Go to first macro def with cursor word', },

{ mode = 'n', keys = '[<C-I>', desc = 'Go to first match with cursor word', },

{ mode = 'n', keys = '[%', desc = 'Go to previous unmatched group' },

{ mode = 'n', keys = '[#', desc = 'Go to previous unmatched #if/#else/#ifdef' },

{ mode = 'n', keys = "['", desc = 'Go to previous mark, first non-blank' },

{ mode = 'n', keys = '[`', desc = 'Go to previous mark' },

{ mode = 'n', keys = '[(', desc = "Go to previous unmatched '('" },

{ mode = 'n', keys = '[/', desc = 'Go to previous C comment start' },

{ mode = 'n', keys = '[*', desc = 'Go to previous C comment start' },

{ mode = 'n', keys = '[I', desc = 'Show lines with cursor word', },

{ mode = 'n', keys = '[D', desc = 'Show macro defs with cursor word' },

{ mode = 'n', keys = '[p', desc = 'Paste with current indent' },

{ mode = 'n', keys = '[P', desc = 'Paste with current indent' },

{ mode = 'n', keys = '[[', desc = 'Go to previous section' },

{ mode = 'n', keys = '[]', desc = 'Go to previous SECTION' },

{ mode = 'n', keys = '[c', desc = 'Go to previous change' },

{ mode = 'n', keys = '[d', desc = 'Show first macro def with cursor word' },

{ mode = 'n', keys = '[f', desc = 'Edit file under cursor' },

{ mode = 'n', keys = '[i', desc = 'Show first line with cursor word', },

{ mode = 'n', keys = '[m', desc = 'Go to previous method start' },

{ mode = 'n', keys = '[M', desc = 'Go to previous method end' },

{ mode = 'n', keys = '[s', desc = 'Go to previous misspelled word' },

{ mode = 'n', keys = '[z', desc = 'Go to current open fold start' },

{ mode = 'n', keys = '[{', desc = "Go to previous unmatched '{'" },

{ mode = 'n', keys = ']<C-D>', desc = 'Go to next macro def with cursor word', },

{ mode = 'n', keys = ']<C-I>', desc = 'Go to next match with cursor word', },

{ mode = 'n', keys = ']%', desc = 'Go to next unmatched group' },

{ mode = 'n', keys = ']#', desc = 'Go to next unmatched #if/#else/#ifdef' },

{ mode = 'n', keys = "]'", desc = "Go to next mark, first non-blank" },

{ mode = 'n', keys = ']`', desc = 'Go to next mark' },

{ mode = 'n', keys = '])', desc = "Go to next unmatched ')'" },

{ mode = 'n', keys = ']/', desc = 'Go to next C comment end' },

{ mode = 'n', keys = ']*', desc = 'Go to next C comment end' },

{ mode = 'n', keys = ']D', desc = 'Show below macro defs with cursor word' },

{ mode = 'n', keys = ']I', desc = 'Show below lines with cursor word', },

{ mode = 'n', keys = ']P', desc = 'Paste with current indent' },

{ mode = 'n', keys = '][', desc = 'Go to next SECTION' },

{ mode = 'n', keys = ']]', desc = 'Go to next section' },

{ mode = 'n', keys = ']c', desc = 'Go to next change' },

{ mode = 'n', keys = ']d', desc = 'Show next macro def with cursor word' },

{ mode = 'n', keys = ']f', desc = 'Edit file under cursor' },

{ mode = 'n', keys = ']i', desc = 'Show next line with cursor word', },

{ mode = 'n', keys = ']m', desc = 'Go to next method start' },

{ mode = 'n', keys = ']M', desc = 'Go to next method end' },

{ mode = 'n', keys = ']p', desc = 'Paste with current indent' },

{ mode = 'n', keys = ']s', desc = 'Go to next misspelled word' },

{ mode = 'n', keys = ']z', desc = 'Go to current open fold end' },

{ mode = 'n', keys = ']}', desc = "Go to next unmatched '}'" },

}

end

--- Generate clues for marks

---

--- Contains clues for the following triggers: >lua

---

--- { mode = { 'n', 'x' }, keys = "'" }

--- { mode = { 'n', 'x' }, keys = "g'" }

--- { mode = { 'n', 'x' }, keys = '`' }

--- { mode = { 'n', 'x' }, keys = 'g`' }

--- <

--- Note: if you use "g" as trigger (like to enable |MiniClue.gen_clues.g()|),

--- don't add "g'" and "g`" as triggers: they already will be taken into account.

---

---@return table Array of clues.

---

---@seealso |mark-motions|

MiniClue.gen_clues.marks = function()

local describe_marks = function(mode, prefix)

local make_clue = function(register, desc) return { mode = mode, keys = prefix .. register, desc = desc } end

return {

make_clue('^', 'Latest insert position'),

make_clue('.', 'Latest change'),

make_clue('"', 'Latest exited position'),

make_clue("'", 'Line before jump'),

make_clue('`', 'Position before jump'),

make_clue('[', 'Start of latest changed or yanked text'),

make_clue(']', 'End of latest changed or yanked text'),

make_clue('(', 'Start of sentence'),

make_clue(')', 'End of sentence'),

make_clue('{', 'Start of paragraph'),

make_clue('}', 'End of paragraph'),

make_clue('<', 'Start of latest visual selection'),

make_clue('>', 'End of latest visual selection'),

}

end

--stylua: ignore

return {

-- Normal and Visual mode

describe_marks({ 'n', 'x' }, "'"),

describe_marks({ 'n', 'x' }, "g'"),

describe_marks({ 'n', 'x' }, "`"),

describe_marks({ 'n', 'x' }, "g`"),

}

end

--- Generate clues for registers

---

--- Contains clues for the following triggers: >lua

---

--- { mode = { 'n', 'x' }, keys = '"' }

--- { mode = { 'i', 'c' }, keys = '<C-r>' }

--- <

---@param opts table|nil Options. Possible keys:

--- - <show_contents> `(boolean)` - whether to show contents of all possible

--- registers. If `false`, only description of special registers is shown.

--- Default: `false`.

---

---@return table Array of clues.

---

---@seealso |registers|

MiniClue.gen_clues.registers = function(opts)

opts = vim.tbl_deep_extend('force', { show_contents = false }, opts or {})

local describe_registers

if opts.show_contents then

describe_registers = H.make_clues_with_register_contents

else

describe_registers = function(mode, prefix)

local make_clue = function(register, desc) return { mode = mode, keys = prefix .. register, desc = desc } end

return {

make_clue('0', 'Latest yank'),

make_clue('1', 'Latest big delete'),

make_clue('"', 'Default register'),

make_clue('#', 'Alternate buffer'),

make_clue('%', 'Name of the current file'),

make_clue('*', 'Selection clipboard'),

make_clue('+', 'System clipboard'),

make_clue('-', 'Latest small delete'),

make_clue('.', 'Latest inserted text'),

make_clue('/', 'Latest search pattern'),

make_clue(':', 'Latest executed command'),

make_clue('=', 'Result of expression'),

make_clue('_', 'Black hole'),

}

end

end

--stylua: ignore

return {

-- Normal and Visual mode

describe_registers({ 'n', 'x' }, '"'),

-- Insert mode

describe_registers('i', '<C-r>'),

{ mode = 'i', keys = '<C-r><C-r>', desc = '+Insert literally' },

describe_registers('i', '<C-r><C-r>'),

{ mode = 'i', keys = '<C-r><C-o>', desc = '+Insert literally + not auto-indent' },

describe_registers('i', '<C-r><C-o>'),

{ mode = 'i', keys = '<C-r><C-p>', desc = '+Insert + fix indent' },

describe_registers('i', '<C-r><C-p>'),

-- Command-line mode

describe_registers('c', '<C-r>'),

{ mode = 'c', keys = '<C-r><C-r>', desc = '+Insert literally' },

describe_registers('c', '<C-r><C-r>'),

{ mode = 'c', keys = '<C-r><C-o>', desc = '+Insert literally' },

describe_registers('c', '<C-r><C-o>'),

}

end

--- Generate clues for window commands

---

--- Contains clues for the following triggers: >lua

---

--- { mode = 'n', keys = '<C-w>' }

--- <

--- Note: only non-duplicated commands are included. For full list see |CTRL-W|.

---

---@param opts table|nil Options. Possible keys:

--- - <submode_move> `(boolean)` - whether to make move (change layout)

--- commands a submode by using `postkeys` field. Default: `false`.

--- - <submode_navigate> `(boolean)` - whether to make navigation (change

--- focus) commands a submode by using `postkeys` field. Default: `false`.

--- - <submode_resize> `(boolean)` - whether to make resize (change size)

--- commands a submode by using `postkeys` field. Default: `false`.

---

---@return table Array of clues.

MiniClue.gen_clues.windows = function(opts)

local default_opts = { submode_navigate = false, submode_move = false, submode_resize = false }

opts = vim.tbl_deep_extend('force', default_opts, opts or {})

local postkeys_move, postkeys_navigate, postkeys_resize = nil, nil, nil

if opts.submode_move then postkeys_move = '<C-w>' end

if opts.submode_navigate then postkeys_navigate = '<C-w>' end

if opts.submode_resize then postkeys_resize = '<C-w>' end