feat: add support for external integrations to hover events (#341)

* feat: add support for external integrations to hover events

It's now possible to create a custom integration in your own
configuration. This can be useful for creating custom behavior when
hovering over a file in yazi. In the future, other events might be
supported as well.

```lua
vim.api.nvim_create_autocmd('User', {
  pattern = 'YaziDDSHover',
  -- see `:help event-args`
  ---@param event {data: YaziHoverEvent}
  callback = function(event)
    vim.notify(
      vim.inspect({ 'Just received a YaziDDSHover event!', event.data })
    )
  end,
})
```

* fixup! feat: add support for external integrations to hover events

README.md

@@ -291,7 +291,7 @@ These are the default keybindings that are available when yazi is open:
       limited to those only
   - `<c-y>`: copy the relative path of the selected file(s) to the clipboard.
     Requires GNU `realpath` or `grealpath` on OSX
-  - `<tab>`: cycle through the open buffers in Neovim. See
+  - `<tab>`: make yazi jump to the open buffers in Neovim. See
     [#232](https://github.com/mikavilpas/yazi.nvim/pull/232) for more
     information
 

integration-tests/cypress/e2e/using-ya-to-read-events/hover-highlights.cy.ts

@@ -42,6 +42,8 @@ describe("highlighting the buffer with 'hover' events", () => {
       // start yazi
       cy.typeIntoTerminal("{upArrow}")
 
+      // yazi should be visible now
+      cy.contains(dir.contents["test-setup.lua"].name)
       hoverAnotherFileToEnsureHoverEventIsReceivedInCI(
         dir.contents["initial-file.txt"].name,
       )
@@ -113,6 +115,8 @@ describe("highlighting the buffer with 'hover' events", () => {
       // start yazi - the initial file should be highlighted
       cy.typeIntoTerminal("{upArrow}")
 
+      // yazi should be visible now
+      cy.contains(dir.contents["test-setup.lua"].name)
       hoverAnotherFileToEnsureHoverEventIsReceivedInCI(testFile)
       isHovered("how to initialize the test environment")
 
@@ -138,6 +142,8 @@ describe("highlighting the buffer with 'hover' events", () => {
         // start yazi
         cy.typeIntoTerminal("{upArrow}")
 
+        // yazi should be visible now
+        cy.contains(dir.contents["test-setup.lua"].name)
         hoverAnotherFileToEnsureHoverEventIsReceivedInCI(
           dir.contents["test-setup.lua"].name,
         )
@@ -171,6 +177,8 @@ describe("highlighting the buffer with 'hover' events", () => {
         // start yazi
         cy.typeIntoTerminal("{upArrow}")
 
+        // yazi should be visible now
+        cy.contains(dir.contents["test-setup.lua"].name)
         hoverAnotherFileToEnsureHoverEventIsReceivedInCI(
           dir.contents["test-setup.lua"].name,
         )
@@ -192,4 +200,33 @@ describe("highlighting the buffer with 'hover' events", () => {
       })
     })
   })
+
+  it("supports external integrations to hover events", () => {
+    startNeovimWithYa({
+      startupScriptModifications: ["notify_hover_events.lua"],
+    }).then((dir) => {
+      // wait until text on the start screen is visible
+      cy.contains("If you see this text, Neovim is ready!")
+
+      // start yazi
+      cy.typeIntoTerminal("{upArrow}")
+
+      // yazi should be visible now
+      cy.contains(dir.contents["test-setup.lua"].name)
+      hoverAnotherFileToEnsureHoverEventIsReceivedInCI(
+        dir.contents["test-setup.lua"].name,
+      )
+
+      // Hovering a new file should have triggered the integration
+      //
+      // the main message from the integration in the
+      // startupScriptModifications script should be visible. Check the file
+      // to see the full integration.
+      cy.contains("Just received a YaziDDSHover event!")
+
+      // some event data should be visible. See the lua type YaziHoverEvent for
+      // the structure
+      cy.contains(`type = "hover"`)
+    })
+  })
 })

integration-tests/server/application/neovim/testEnvironmentTypes.ts

@@ -29,6 +29,7 @@ export const startupScriptModification = z.enum([
   "use_light_neovim_colorscheme.lua",
   "modify_yazi_config_and_set_help_key.lua",
   "disable_a_keybinding.lua",
+  "notify_hover_events.lua",
 ])
 export type StartupScriptModification = z.infer<
   typeof startupScriptModification

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

@@ -0,0 +1,14 @@
+---@module "yazi"
+
+require('yazi')
+
+vim.api.nvim_create_autocmd('User', {
+  pattern = 'YaziDDSHover',
+  -- see `:help event-args`
+  ---@param event {data: YaziHoverEvent}
+  callback = function(event)
+    vim.notify(
+      vim.inspect({ 'Just received a YaziDDSHover event!', event.data })
+    )
+  end,
+})

lua/yazi.lua

@@ -15,7 +15,7 @@ M.previous_state = {}
 function M.yazi(config, input_path)
   local utils = require('yazi.utils')
   local YaziProcess = require('yazi.process.yazi_process')
-  local event_handling = require('yazi.event_handling')
+  local yazi_event_handling = require('yazi.event_handling.yazi_event_handling')
 
   if utils.is_yazi_available() ~= true then
     print('Please install yazi. Check the documentation for more information')
@@ -72,7 +72,8 @@ function M.yazi(config, input_path)
         )
       )
 
-      local event_info = event_handling.process_events_emitted_from_yazi(events)
+      local event_info =
+        yazi_event_handling.process_events_emitted_from_yazi(events)
 
       local last_directory = event_info.last_directory
       if last_directory == nil then

lua/yazi/buffer_highlighting/highlight_hovered_buffer.lua

@@ -5,6 +5,8 @@ local DisposableHighlight =
 
 local M = {}
 
+---@alias WindowId integer
+
 -- The currently highlighted windows. Global because there can only be one yazi
 -- at a time.
 ---@type table<WindowId, yazi.DisposableHighlight>

lua/yazi/event_handling/nvim_event_handling.lua

@@ -0,0 +1,17 @@
+-- This file is about emitting events to other Neovim plugins
+
+local M = {}
+
+---@alias YaziNeovimEvent
+---| "'YaziDDSHover'" A file was hovered over in yazi
+
+---@param event_name YaziNeovimEvent
+---@param event_data table
+function M.emit(event_name, event_data)
+  vim.api.nvim_exec_autocmds('User', {
+    pattern = event_name,
+    data = event_data,
+  })
+end
+
+return M

lua/yazi/event_handling.lua → lua/yazi/event_handling/yazi_event_handling.lua

@@ -1,3 +1,5 @@
+-- This file is about handling events that are sent from yazi
+
 local utils = require('yazi.utils')
 local plenaryIterators = require('plenary.iterators')
 local plenary_path = require('plenary.path')

lua/yazi/process/ya_process.lua

@@ -1,7 +1,5 @@
 ---@module "plenary.path"
 
----@alias WindowId integer
-
 local Log = require('yazi.log')
 local utils = require('yazi.utils')
 local highlight_hovered_buffer =
@@ -133,6 +131,10 @@ function YaProcess:start()
               event.url,
               self.config.highlight_groups
             )
+
+            local event_handling =
+              require('yazi.event_handling.nvim_event_handling')
+            event_handling.emit('YaziDDSHover', event)
           end)
         else
           self.events[#self.events + 1] = event

spec/yazi/delete_spec.lua

@@ -1,5 +1,5 @@
 local assert = require('luassert')
-local event_handling = require('yazi.event_handling')
+local yazi_event_handling = require('yazi.event_handling.yazi_event_handling')
 
 describe('process_delete_event', function()
   before_each(function()
@@ -20,7 +20,7 @@ describe('process_delete_event', function()
       data = { urls = { '/abc/def' } },
     }
 
-    event_handling.process_delete_event(event, {})
+    yazi_event_handling.process_delete_event(event, {})
 
     vim.wait(1000, function()
       return not vim.api.nvim_buf_is_valid(buffer)
@@ -39,7 +39,7 @@ describe('process_delete_event', function()
       data = { urls = { '/abc' } },
     }
 
-    event_handling.process_delete_event(event, {})
+    yazi_event_handling.process_delete_event(event, {})
 
     vim.wait(1000, function()
       return not vim.api.nvim_buf_is_valid(buffer)
@@ -58,7 +58,7 @@ describe('process_delete_event', function()
       data = { urls = { '/abc/ghi' } },
     }
 
-    local deletions = event_handling.process_delete_event(event, {})
+    local deletions = yazi_event_handling.process_delete_event(event, {})
 
     -- NOTE waiting for something not to happen is not possible to do reliably.
     -- Inspect the return value so we can at least get some level of
@@ -86,7 +86,7 @@ describe('process_delete_event', function()
     }
 
     local deletions =
-      event_handling.process_delete_event(delete_event, { rename_event })
+      yazi_event_handling.process_delete_event(delete_event, { rename_event })
 
     assert.are.same({}, deletions)
   end)

spec/yazi/move_spec.lua

@@ -1,5 +1,5 @@
 local assert = require('luassert')
-local event_handling = require('yazi.event_handling')
+local yazi_event_handling = require('yazi.event_handling.yazi_event_handling')
 
 describe('get_buffers_that_need_renaming_after_yazi_exited', function()
   before_each(function()
@@ -21,7 +21,7 @@ describe('get_buffers_that_need_renaming_after_yazi_exited', function()
     vim.fn.bufadd('/my-tmp/file_A')
 
     local instructions =
-      event_handling.get_buffers_that_need_renaming_after_yazi_exited(
+      yazi_event_handling.get_buffers_that_need_renaming_after_yazi_exited(
         move_event
       )
 
@@ -45,7 +45,7 @@ describe('get_buffers_that_need_renaming_after_yazi_exited', function()
       vim.fn.bufadd('/my-tmp/dir1/file')
 
       local instructions =
-        event_handling.get_buffers_that_need_renaming_after_yazi_exited(
+        yazi_event_handling.get_buffers_that_need_renaming_after_yazi_exited(
           move_event
         )
 
@@ -66,7 +66,7 @@ describe('get_buffers_that_need_renaming_after_yazi_exited', function()
     vim.fn.bufadd('/my-tmp/dir1/file')
 
     local instructions =
-      event_handling.get_buffers_that_need_renaming_after_yazi_exited(
+      yazi_event_handling.get_buffers_that_need_renaming_after_yazi_exited(
         move_event
       )
 

spec/yazi/rename_spec.lua

@@ -1,5 +1,5 @@
 local assert = require('luassert')
-local event_handling = require('yazi.event_handling')
+local yazi_event_handling = require('yazi.event_handling.yazi_event_handling')
 local utils = require('yazi.utils')
 
 describe('get_buffers_that_need_renaming_after_yazi_exited', function()
@@ -22,7 +22,7 @@ describe('get_buffers_that_need_renaming_after_yazi_exited', function()
     vim.fn.bufadd('/my-tmp/file_A')
 
     local rename_instructions =
-      event_handling.get_buffers_that_need_renaming_after_yazi_exited(
+      yazi_event_handling.get_buffers_that_need_renaming_after_yazi_exited(
         rename_event
       )
 
@@ -46,7 +46,7 @@ describe('get_buffers_that_need_renaming_after_yazi_exited', function()
       vim.fn.bufadd('/my-tmp/dir1/file')
 
       local rename_instructions =
-        event_handling.get_buffers_that_need_renaming_after_yazi_exited(
+        yazi_event_handling.get_buffers_that_need_renaming_after_yazi_exited(
           rename_event
         )
 
@@ -67,7 +67,7 @@ describe('get_buffers_that_need_renaming_after_yazi_exited', function()
     vim.fn.bufadd('/my-tmp/dir1/file')
 
     local rename_instructions =
-      event_handling.get_buffers_that_need_renaming_after_yazi_exited(
+      yazi_event_handling.get_buffers_that_need_renaming_after_yazi_exited(
         rename_event
       )
 
@@ -98,7 +98,7 @@ describe('process_events_emitted_from_yazi', function()
       id = '123',
     }
 
-    event_handling.process_events_emitted_from_yazi({ event })
+    yazi_event_handling.process_events_emitted_from_yazi({ event })
 
     local open_buffers = utils.get_open_buffers()
     for _, buffer in ipairs(open_buffers) do
@@ -125,7 +125,7 @@ describe('process_events_emitted_from_yazi', function()
       },
     }
 
-    event_handling.process_events_emitted_from_yazi({ event })
+    yazi_event_handling.process_events_emitted_from_yazi({ event })
 
     local open_buffers = utils.get_open_buffers()
     for _, buffer in ipairs(open_buffers) do

spec/yazi/trash_spec.lua

@@ -1,5 +1,5 @@
 local assert = require('luassert')
-local event_handling = require('yazi.event_handling')
+local yazi_event_handling = require('yazi.event_handling.yazi_event_handling')
 
 describe('process_trash_event', function()
   before_each(function()
@@ -20,7 +20,7 @@ describe('process_trash_event', function()
       data = { urls = { '/abc/def' } },
     }
 
-    event_handling.process_delete_event(event, {})
+    yazi_event_handling.process_delete_event(event, {})
 
     vim.wait(1000, function()
       return not vim.api.nvim_buf_is_valid(buffer)
@@ -40,7 +40,7 @@ describe('process_trash_event', function()
       data = { urls = { '/abc' } },
     }
 
-    event_handling.process_delete_event(event, {})
+    yazi_event_handling.process_delete_event(event, {})
 
     vim.wait(1000, function()
       return not vim.api.nvim_buf_is_valid(buffer)
@@ -60,7 +60,7 @@ describe('process_trash_event', function()
       data = { urls = { '/abc/ghi' } },
     }
 
-    local deletions = event_handling.process_delete_event(event, {})
+    local deletions = yazi_event_handling.process_delete_event(event, {})
     assert.are.same({}, deletions)
   end)
 
@@ -84,7 +84,7 @@ describe('process_trash_event', function()
     }
 
     local deletions =
-      event_handling.process_delete_event(delete_event, { rename_event })
+      yazi_event_handling.process_delete_event(delete_event, { rename_event })
     assert.are.same({}, deletions)
   end)
 end)