feat: can toggle help menu with <f1> key in the yazi window (#275)

When yazi is open, you can now press `<f1>` to show a help menu with all
the keybindings. This is useful for new users who are not yet familiar
with the keybindings.

README.md

@@ -20,7 +20,7 @@ open yazi in a floating window in Neovim.
 
 ## ✨ Features
 
-- Open yazi in a floating window
+- Open yazi in a floating window. Press `<f1>` to display all keymaps!
 - Files can be selected in yazi and opened in the current buffer, a vertical
   split, a horizontal split, or a new tab
 - If multiple files are selected, they can be sent to the quickfix list
@@ -102,6 +102,10 @@ This is the preferred installation method.
     -- enable these if you are using the latest version of yazi
     -- use_ya_for_events_reading = true,
     -- use_yazi_client_id_flag = true,
+
+    keymaps = {
+      show_help = '<f1>',
+    },
   },
 }
 ```
@@ -201,6 +205,7 @@ You can optionally configure yazi.nvim by setting any of the options below.
     -- - use e.g. `open_file_in_tab = false` to disable a keymap
     -- - you can customize only some of the keymaps if you want
     keymaps = {
+      show_help = '<f1>',
       open_file_in_vertical_split = '<c-v>',
       open_file_in_horizontal_split = '<c-x>',
       open_file_in_tab = '<c-t>',

integration-tests/client/testEnvironmentTypes.ts

@@ -20,6 +20,7 @@ export type StartupScriptModification =
   | "modify_yazi_config_and_add_hovered_buffer_background.lua"
   | "use_light_neovim_colorscheme.lua"
   | "report_loaded_yazi_modules.lua"
+  | "modify_yazi_config_and_set_help_key.lua"
 
 declare global {
   interface Window {

integration-tests/cypress/e2e/help-menu.cy.ts

@@ -0,0 +1,51 @@
+import assert = require("assert")
+import { startNeovimWithYa } from "./using-ya-to-read-events/startNeovimWithYa"
+
+describe("the help menu", () => {
+  it("can show help with a keymap", () => {
+    cy.visit("http://localhost:5173")
+    startNeovimWithYa({
+      startupScriptModifications: ["modify_yazi_config_and_set_help_key.lua"],
+    }).then((dir) => {
+      // wait until text on the start screen is visible
+      cy.contains("If you see this text, Neovim is ready!")
+
+      // open yazi and wait for it to load
+      cy.typeIntoTerminal("{upArrow}")
+      cy.contains(dir.contents["test-setup.lua"].name)
+
+      cy.typeIntoTerminal("{del}")
+      cy.contains("yazi.nvim help")
+
+      // the config for this test overrides the help key to be <del>. Make sure
+      // overrides are shown
+      cy.contains("<del> - show this help")
+
+      // the version of yazi.nvim should be shown
+      cy.readFile("../.release-please-manifest.json").then(
+        (yaziNvimManifest: unknown) => {
+          assert(typeof yaziNvimManifest === "object")
+          assert(yaziNvimManifest)
+          assert("." in yaziNvimManifest)
+          assert(typeof yaziNvimManifest["."] === "string")
+          cy.contains(`version ${yaziNvimManifest["."]}`)
+        },
+      )
+
+      // The help buffer must not be modifiable. Don't assert the text as it
+      // may be translated to the developer's own language.
+      cy.typeIntoTerminal("i")
+      cy.contains("E21") // Cannot make changes, 'modifiable' is off
+
+      // close the help buffer. It should enable insert mode in the yazi buffer.
+      cy.typeIntoTerminal("q")
+      cy.contains("yazi.nvim help").should("not.exist")
+
+      // it should now be possible to close yazi, since it's in insert mode
+      // and ready to accept commands
+      cy.contains(dir.contents["test-setup.lua"].name)
+      cy.typeIntoTerminal("q")
+      cy.contains(dir.contents["test-setup.lua"].name).should("not.exist")
+    })
+  })
+})

integration-tests/server/server.ts

@@ -83,6 +83,15 @@ io.on("connection", function connection(socket) {
               args.push("-c", `lua dofile('${file}')`)
               break
             }
+            case "modify_yazi_config_and_set_help_key.lua": {
+              const file = path.join(
+                testDirectory,
+                "config-modifications",
+                "modify_yazi_config_and_set_help_key.lua",
+              )
+              args.push("-c", `lua dofile('${file}')`)
+              break
+            }
             default:
               modification satisfies never
               throw new Error(

integration-tests/test-environment/config-modifications/modify_yazi_config_and_set_help_key.lua

@@ -0,0 +1,14 @@
+---@module "yazi"
+
+-- The reason to set a different yazi.nvim help key is that Cypress, the
+-- current test runner, does not natively support function keys such as <f1>
+-- https://docs.cypress.io/api/commands/type#Arguments
+
+require('yazi').setup(
+  ---@type YaziConfig
+  {
+    keymaps = {
+      show_help = '<del>',
+    },
+  }
+)

lua/yazi/config.lua

@@ -20,6 +20,7 @@ function M.default()
       grep_in_directory = '<c-s>',
       replace_in_directory = '<c-g>',
       cycle_open_buffers = '<tab>',
+      show_help = '<f1>',
     },
     set_keymappings_function = nil,
     hooks = {
@@ -153,6 +154,53 @@ function M.set_keymappings(yazi_buffer, config, context)
       })
     end, { buffer = yazi_buffer })
   end
+
+  if config.keymaps.show_help ~= false then
+    vim.keymap.set({ 't' }, config.keymaps.show_help, function()
+      local w = vim.api.nvim_win_get_width(0)
+      local h = vim.api.nvim_win_get_height(0)
+
+      local help_buffer = vim.api.nvim_create_buf(false, true)
+      local win = vim.api.nvim_open_win(help_buffer, true, {
+        style = 'minimal',
+        relative = 'win',
+        bufpos = { 5, 30 },
+        noautocmd = true,
+        width = math.min(40, math.floor(w * 0.5)),
+        height = math.min(11, math.floor(h * 0.5)),
+        border = config.yazi_floating_window_border,
+      })
+
+      -- write the help text. Hopefully the vim help syntax is always bundled
+      -- and available so that nice highlights can be shown.
+      vim.api.nvim_buf_set_lines(help_buffer, 0, -1, false, {
+        'yazi.nvim help (`q` to close):',
+        '',
+        '' .. config.keymaps.open_file_in_tab .. ' - open file in tab',
+        ''
+          .. config.keymaps.open_file_in_horizontal_split
+          .. ' - open file in horizontal split',
+        ''
+          .. config.keymaps.open_file_in_vertical_split
+          .. ' - open file in vertical split',
+        '' .. config.keymaps.grep_in_directory .. ' - search in directory',
+        '' .. config.keymaps.replace_in_directory .. ' - replace in directory',
+        '' .. config.keymaps.cycle_open_buffers .. ' - cycle open buffers',
+        '' .. config.keymaps.show_help .. ' - show this help',
+        '',
+        'version *' .. require('yazi').version .. '*',
+      })
+
+      vim.api.nvim_set_option_value('filetype', 'help', { buf = help_buffer })
+      vim.api.nvim_set_option_value('modifiable', false, { buf = help_buffer })
+
+      -- exit with q
+      vim.keymap.set({ 'n' }, 'q', function()
+        vim.api.nvim_win_close(win, true)
+        vim.cmd('startinsert')
+      end, { buffer = help_buffer })
+    end, { buffer = yazi_buffer })
+  end
 end
 
 ---@param yazi_buffer integer

lua/yazi/types.lua

@@ -29,6 +29,7 @@
 ---@field grep_in_directory? YaziKeymap # Close yazi and open a grep (default: telescope) narrowed to the directory yazi is in
 ---@field replace_in_directory? YaziKeymap # Close yazi and open a replacer (default: grug-far.nvim) narrowed to the directory yazi is in
 ---@field cycle_open_buffers? YaziKeymap # When Neovim has multiple splits open and visible, make yazi jump to the directory of the next one
+---@field show_help? YaziKeymap # Show a help menu with all the keybindings
 
 ---@class (exact) YaziActiveContext # context state for a single yazi session
 ---@field api YaziProcessApi