[mini.jump2d] Jump with second character from each spot

[abeldekat]

jump2d_include_second_character.mp4

Left: Jump2d
Right: Leap

The most important reason why I still use leap: Its promise that the second character of the spot I am targeting can always be typed after initiating the search. That way, I have more time to process the generated third char, which is shown immediately.

I would like to use jump2d, and have been thinking about an idiomatic implementation starting from MiniJump2d.builtin.single_character:

• on start, dim immediately. Otherwise, there is no indication of activity until the user enters the first character
• n_steps_ahead should be high
• the labels should stay in place when typing
• on start, group by the second character of each spot. Generate labels as usual per group

I am using this branch in my fork of mini.nvim.

Init.lua:

---@diagnostic disable: undefined-global
local function setup_deps(path_to_site)
  local mini_path = path_to_site .. "pack/deps/start/mini.nvim"
  if not vim.uv.fs_stat(mini_path) then
    vim.cmd('echo "Installing `mini.nvim`" | redraw')
    -- vim.fn.system({ "git", "clone", "--filter=blob:none", "https://github.com/echasnovski/mini.nvim", mini_path })
    vim.fn.system({
      "git",
      "clone",
      "--filter=blob:none",
      "https://github.com/abeldekat/mini.nvim",
      "--branch=jump2d_include_second_character",
      mini_path,
    })
    vim.cmd("packadd mini.nvim | helptags ALL")
    vim.cmd('echo "Installed `mini.nvim`" | redraw')
  end
  require("mini.deps").setup({ path = { package = path_to_site } })
end
setup_deps(vim.fn.stdpath("data") .. "/site/")

local H = {}
vim.g.mapleader = " "
local setup = function()
  MiniDeps.now(function()
    require("mini.basics").setup()
    vim.cmd.colorscheme("randomhue")
    vim.api.nvim_create_autocmd("FileType", {
      pattern = { "lua" },
      callback = function() pcall(vim.treesitter.start) end,
    })

    local allowed_windows = { current = true, not_current = true }
    local group_dim, ns_id_dim = "LeapBackdrop", vim.api.nvim_create_namespace("MiniJump2dDimImmediately")
    require("mini.jump2d").setup({
      allowed_windows = allowed_windows,
      hl_group = group_dim,
      hl_group_ahead = "LeapLabel",
      labels = "jkl;mhniosde",
      mappings = { start_jumping = "" },
      silent = true,
      view = { dim = false, fixed_steps = true }, -- NOTE: New property fixed_steps
    })

    local single_character_extended = function()
      H.dim_immediately(ns_id_dim, group_dim, allowed_windows)
      MiniJump2d.start(MiniJump2d.builtin_opts.single_character_extended) -- NOTE: New builtin
      H.dim_remove(ns_id_dim, allowed_windows)
    end
    vim.keymap.set({ "n", "x", "o" }, "s", single_character_extended, { desc = "Start 2d jumping" })
  end)
end

H.dim_immediately = function(ns, group, allowed_windows)
  for _, win_id in ipairs(H.list_wins(allowed_windows)) do
    local wininfo = vim.fn.getwininfo(win_id)[1]
    --stylua: ignore
    vim.highlight.range(
      wininfo.bufnr, ns, group,
      { wininfo.topline - 1, 0 }, { wininfo.botline - 1, -1 }, { priority = 9999 }
    )
  end
  vim.cmd("redraw")
end

H.dim_remove = function(ns, allowed_windows)
  for _, win_id in ipairs(H.list_wins(allowed_windows)) do
    pcall(vim.api.nvim_buf_clear_namespace, vim.api.nvim_win_get_buf(win_id), ns, 0, -1)
  end
end

H.list_wins = function(allowed_windows)
  local win_id_init = vim.api.nvim_get_current_win()
  return vim.tbl_filter(function(win_id)
    if win_id == win_id_init then return allowed_windows.current end
    return allowed_windows.not_current
  end, vim.api.nvim_list_wins())
end

setup()

Notes:

• I could not find an easy way to add "dim immediately" to jump2d.lua
• I can imagine that spots_add_steps does not have to be public. Perhaps an internal table, returning a custom function when the spotter has a certain id?

cc: @pkazmier

See also: Improve 'mini.jump2d' default config and jumping experience

[echasnovski]

Thanks for sharing!

• on start, dim immediately. Otherwise, there is no indication of activity until the user enters the first character

This for me breaks the purpose of dimming in the first place: indicate that certain lines have matches (while making labels more visible). If there is dimming before jumping has started, then this interpretation breaks (as before jumping all lines are dimmed). I don't think I like that.

• n_steps_ahead should be high
• the labels should stay in place when typing

Unfortunately, both of these do not go well together, because labels can overlap. Like in case of several consecutive same characters for single_character case. If they stay in place, not-first character of label sequence can be hidden behind the labels from the right neighbor match.

There are solutions, of course. Like dynamically hiding already typed letter of matched spots (to clear the space for possible later labels from left to be visible). Or like showing only a single step ahead (like 'leap.nvim' seems to be doing).

But I am not a fan of showing labels not at the target spot. Every time I tried it, it was always confusing to adapt to.

In theory, showing labels one or two steps to the right is possible with a tweaked spotter:

• Actually match spots that are one or two steps to the right of the target ones.
• Use hooks.after_jump to adjust cursor.

This would still only show labels after one or two keys are typed, yes.

[abeldekat]

I really don't like the idea of showing labels at the spot while requiring user to press a key to the right of it.

@echasnovski, given the quote above, and since it most likely will not be easily possible to show any labels before spotter is computed, I am considering to fork jump2d. I have ideas to change the code into a "minimal" leap replacement.

If I decide to do so, I expect to reuse a substantial amount of your excellent work, including comments and tests.

Do you think that the use-case is sufficiently different from the intended usage of mini.jump2d in order to justify a fork?

[echasnovski]

I really don't like the idea of showing labels at the spot while requiring user to press a key to the right of it.

@echasnovski, given the quote above ...

It should already be possible to show labels to the right of the keys, just as in 'leap.nvim': offset computed jump spots to the right and have hooks.after_jump adjust cursor. The rework in #1818 will make it even easier. Plus I am thinking about adding this as something like config.view.offset_labels (could be set to 2 in this case to be shown at the right of two cells).

If I decide to do so, I expect to reuse a substantial amount of your excellent work, including comments and tests.

Do you think that the use-case is sufficiently different from the intended usage of mini.jump2d in order to justify a fork?

If it is only to show labels after the first key press and dim all lines - I don't think so (sorry). Of course, you are free to ignore this and fork with proper attribution.

But the #1818 rewrite will still happen (not immediately, but hopefully in this 'mini.nvim' version development cycle) and I'll still think about an organic way to control label display (just can't think of any right now).

[abeldekat]

I can certainly wait, and see if the rewrite allows me to achieve what I'm currently having in the fork I am using in my own config (described in this comment). I don't mind having an extended configuration on top of a mini module, and for now an incidental git rebase -i main is doable.

Given the current code, I would need to be able to:

• Override H.spot_add_steps
• Override H.spots_show
• Replace if vim.tbl_contains(label_tbl, key) then with if not (key == H.keys.cr or key == H.keys.esc or key == H.keys.block_operator_pending) then in H.advance_jump

Regarding that third point, all tests pass. Without the user overriding code in the first two points, the prerequisite that each presented label needs to be in config.labels still holds true. I have seen that ability to override parts of the algorithm in for example mini.snippets.

It's not about dimming, I can easily do that myself. It very much is about seeing the generated label after typing the jump initializer, implying the second character will also be given.

I am a bit surprised how much I like the approach from this comment.

I do understand the argument about the “right-left” eye movement. It's also a matter of habit and practice I think. When I select a target, I already know the first two characters. Thus, I can keep my eyes on the ball on target position, typing fluently.

I also don't mind two labels hiding the cell to the right. That will happen when I have already entered the jump indentifier. As I know the second character, I don't need to see it.
It won't happen on three consecutive characters that are the same. In that case, mini.jump2d already makes sure that all targets are reachable, based on the algorithm in H.spots_to_extmarks.

[abeldekat]

Using my local fork, I added some improvements, especially for buffers without much text.

Quite often, when supplying jump initializer -> second character, there is no generated label because the combination is unique. I now show the middledot on target position in that case.

Sometimes, the jump is immediate when the jump initializer is unique. For example, in the video below, in the last jump to workflow/visits.lua, the v is unique.
When I type the first two characters, the second i enters insert mode... I added an extra option to MiniJump2d.start to prevent that, forcing the second character to always be requested:

---...

  if #spots == 1 and not opts.force_filtering then
    H.perform_jump(spots[1], opts.hooks.after_jump)
    return
  end

---...

These changes are especially nice in mini.files, in combination with file after/ftplugin/minifiles.lua:

vim.b.minijump2d_config = {
  allowed_windows = { current = true, not_current = false },
}

By default, inside mini.files labels are also generated in all other windows, which is not necessary.

I am also experimenting with the labels, trying to increase the chance of being able to alternate between the left and right hand:

  -- Have left hand labels grouped around s:
  labels = "jskdlwmeixoc", -- 12 labels alternated "js", "kd", "lw", "me", "ix", "oc"

Video mini.files:

jump2d_mini_files.mp4

[echasnovski]

I am also experimenting with the labels, trying to increase the chance of being able to alternate between the left and right hand:

Yes, I had similar idea, but around having two sets of labels. Something like asdfg and hjkl; Those might alternate directly when computing label steps. But the problem is that it visibly increases the average number of keys users need to type. it can be solved by going outside of home row (like asdfgrevc and hjkl;uinm), but I think using only home row is pretty useful.