feat(preview): add snacks.image integration (#1815)

pynappo · web-flow · commit fba6d1f9b5ed · 2025-07-04T23:27:17.000-07:00
diff --git a/.github/workflows/.luarc-5.1.json b/.github/workflows/.luarc-5.1.json
@@ -18,6 +18,7 @@
       "$PWD/.dependencies/pack/vendor/start/plenary.nvim",
       "$PWD/.dependencies/pack/vendor/start/nui.nvim",
       "$PWD/.dependencies/pack/vendor/start/nvim-web-devicons",
+      "$PWD/.dependencies/pack/vendor/start/snacks.nvim",
       "${3rd}/luassert",
       "${3rd}/busted",
       "${3rd}/luv",
diff --git a/.github/workflows/.luarc-luajit-master.json b/.github/workflows/.luarc-luajit-master.json
@@ -18,6 +18,7 @@
       "$PWD/.dependencies/pack/vendor/start/plenary.nvim",
       "$PWD/.dependencies/pack/vendor/start/nui.nvim",
       "$PWD/.dependencies/pack/vendor/start/nvim-web-devicons",
+      "$PWD/.dependencies/pack/vendor/start/snacks.nvim",
       "${3rd}/luassert",
       "${3rd}/busted",
       "${3rd}/luv",
diff --git a/.lazy.lua b/.lazy.lua
@@ -0,0 +1,20 @@
+local root = vim.fs.find({ "neo-tree.nvim" }, { upward = true })[1]
+local deps_dir = root .. "/.dependencies/pack/vendor/start"
+return {
+  {
+    "folke/snacks.nvim",
+    dir = deps_dir .. "/snacks.nvim",
+  },
+  {
+    "MunifTanjim/nui.nvim",
+    dir = deps_dir .. "/nui.nvim",
+  },
+  {
+    "nvim-tree/nvim-web-devicons",
+    dir = deps_dir .. "/nvim-web-devicons",
+  },
+  {
+    "nvim-lua/plenary.nvim",
+    dir = deps_dir .. "/plenary.nvim",
+  },
+}
diff --git a/.luarc.json b/.luarc.json
@@ -18,6 +18,7 @@
       "$PWD/.dependencies/pack/vendor/start/plenary.nvim",
       "$PWD/.dependencies/pack/vendor/start/nui.nvim",
       "$PWD/.dependencies/pack/vendor/start/nvim-web-devicons",
+      "$PWD/.dependencies/pack/vendor/start/snacks.nvim",
       "${3rd}/luassert",
       "${3rd}/busted",
       "${3rd}/luv",
diff --git a/Makefile b/Makefile
@@ -27,7 +27,10 @@ $(DEPS)/nvim-web-devicons: $(DEPS)
 $(DEPS)/plenary.nvim: $(DEPS)
 	@test -d "$(DEPS)/plenary.nvim" || git clone https://github.com/nvim-lua/plenary.nvim "$(DEPS)/plenary.nvim"
 
-setup: $(DEPS)/nui.nvim $(DEPS)/nvim-web-devicons $(DEPS)/plenary.nvim
+$(DEPS)/snacks.nvim: $(DEPS)
+	@test -d "$(DEPS)/snacks.nvim" || git clone https://github.com/folke/snacks.nvim "$(DEPS)/snacks.nvim"
+
+setup: $(DEPS)/nui.nvim $(DEPS)/nvim-web-devicons $(DEPS)/plenary.nvim $(DEPS)/snacks.nvim
 	@echo "[setup] environment ready"
 
 .PHONY: clean
diff --git a/README.md b/README.md
@@ -60,7 +60,7 @@ so we can fix it.
 > You do not need to call `require('neo-tree').setup({ ... })` for Neo-tree to work. `setup()` is only used for
 > configuration.
 
-#### Minimal Example for Lazy:
+#### Minimal Example for lazy.nvim:
 ```lua
 {
   "nvim-neo-tree/neo-tree.nvim",
@@ -69,13 +69,16 @@ so we can fix it.
     "nvim-lua/plenary.nvim",
     "nvim-tree/nvim-web-devicons", -- not strictly required, but recommended
     "MunifTanjim/nui.nvim",
-    -- {"3rd/image.nvim", opts = {}}, -- Optional image support in preview window: See `# Preview Mode` for more information
+    -- Optional image support for file preview: See `# Preview Mode` for more information.
+    -- {"3rd/image.nvim", opts = {}},
+    -- OR use snacks.nvim's image module:
+    -- "folke/snacks.nvim",
   },
   lazy = false, -- neo-tree will lazily load itself
   ---@module "neo-tree"
   ---@type neotree.Config?
   opts = {
-    -- fill any relevant options here
+    -- add options here
   },
 }
 ```
@@ -89,7 +92,10 @@ use({
     "nvim-lua/plenary.nvim",
     "nvim-tree/nvim-web-devicons", -- not strictly required, but recommended
     "MunifTanjim/nui.nvim",
-    -- "3rd/image.nvim", -- Optional image support in preview window: See `# Preview Mode` for more information
+    -- Optional image support in preview window: See `# Preview Mode` for more information
+    -- { "3rd/image.nvim", config = function() require('image').setup({}) end },
+    -- OR use snacks.nvim's image module:
+    -- "folke/snacks.nvim",
   }
 })
 ```
@@ -153,10 +159,6 @@ return {
       },
     },
     lazy = false,
-    -----Instead of using `config`, you can use `opts` instead, if you'd like:
-    -----@module "neo-tree"
-    -----@type neotree.Config
-    --opts = {},
     config = function()
       -- If you want icons for diagnostic errors, you'll need to define them somewhere.
       -- In Neovim v0.10+, you can configure them in vim.diagnostic.config(), like:
@@ -178,6 +180,8 @@ return {
       -- vim.fn.sign_define("DiagnosticSignInfo", { text = " ", texthl = "DiagnosticSignInfo" })
       -- vim.fn.sign_define("DiagnosticSignHint", { text = "󰌵", texthl = "DiagnosticSignHint" })
 
+      vim.keymap.set("n", "<leader>e", "<Cmd>Neotree reveal<CR>")
+
       require("neo-tree").setup({
         close_if_last_window = false, -- Close Neo-tree if it is the last window left in the tab
         popup_border_style = "NC", -- or "" to use 'winborder' on Neovim v0.11+
@@ -300,7 +304,14 @@ return {
             ["<2-LeftMouse>"] = "open",
             ["<cr>"] = "open",
             ["<esc>"] = "cancel", -- close preview or floating neo-tree window
-            ["P"] = { "toggle_preview", config = { use_float = true, use_image_nvim = true } },
+            ["P"] = {
+              "toggle_preview",
+              config = {
+                use_float = true,
+                use_snacks_image = true,
+                use_image_nvim = true,
+              },
+            },
             -- Read `# Preview Mode` for more information
             ["l"] = "focus_preview",
             ["S"] = "open_split",
@@ -507,8 +518,6 @@ return {
           },
         },
       })
-
-      vim.keymap.set("n", "<leader>e", "<Cmd>Neotree reveal<CR>")
     end,
   },
 }
@@ -807,6 +816,7 @@ require("neo-tree").setup({
         config = {
           use_float = false,
           -- use_image_nvim = true,
+          -- use_snacks_image = true,
           -- title = 'Neo-tree Preview',
         },
       },
@@ -831,11 +841,13 @@ window as being used as a preview.
 
 #### Image Support in Preview Mode
 
-If you have [3rd/image.nvim](https://github.com/3rd/image.nvim) installed, preview
+If you have [folke/snacks.nvim](https://github.com/folke/snacks.nvim/blob/main/docs/image.md)
+or [3rd/image.nvim](https://github.com/3rd/image.nvim) installed, preview
 mode supports image rendering by default using kitty graphics protocol or ueberzug
 ([Video](https://user-images.githubusercontent.com/41065736/277180763-b7152637-f310-43a5-b8c3-4bcba135629d.mp4)).
-However, if you do not want this feature, you can disable it by changing the option
-`use_image_nvim = false` in the mappings config mentioned above.
+
+However, if you do not want this feature, you can disable it by setting
+`use_snacks_image = false` or `use_image_nvim = false` in the mappings config mentioned above.
 
 ## Configuration and Customization
 
diff --git a/doc/neo-tree.txt b/doc/neo-tree.txt
@@ -430,7 +430,14 @@ an existing split by configuring the command like this:
     require("neo-tree").setup({
       window = {
         mappings = {
-          ["P"] = { "toggle_preview", config = { use_float = false, use_image_nvim = true } },
+          ["P"] = {
+            "toggle_preview",
+            config = {
+              use_float = false,
+              use_snacks_image = true,
+              use_image_nvim = true
+            }
+          },
           ["l"] = "focus_preview",
           ["<C-b>"] = { "scroll_preview", config = {direction = 10} },
           ["<C-f>"] = { "scroll_preview", config = {direction = -10} },
@@ -450,10 +457,15 @@ variable `neo_tree_preview` set to `1` to indicate that it is being used as a
 preview window. You can refer to this in statusline and winbar configs to mark a
 window as being used as a preview.
 
-If you have [3rd/image.nvim](https://github.com/3rd/image.nvim) installed, preview
-mode supports image rendering by default using kitty graphics protocol or ueberzug.
-However, if you do not want this feature, you can disable it by changing the option
-`use_image_nvim = false` in the mappings config mentioned above.
+If you have folke/snacks.nvim or 3rd/image.nvim installed, preview mode supports
+image rendering by default using kitty graphics protocol or ueberzug.
+
+- https://github.com/folke/snacks.nvim/blob/main/docs/image.md
+- https://github.com/3rd/image.nvim
+
+However, if you do not want this feature, you can disable it by setting
+`use_snacks_image = false` or `use_image_nvim = false` in the mappings config
+mentioned above.
 
 CUSTOM MAPPINGS                                       *neo-tree-custom-mappings*
 
diff --git a/lua/neo-tree/collections.lua b/lua/neo-tree/collections.lua
@@ -96,7 +96,7 @@ function Queue:for_each(func)
         node_is_next = true
         self._list:remove_node(node_to_remove)
       elseif type(result) == "table" then
-        if type(result.handled) == "boolean" and result.handled == true then
+        if result.handled == true then
           log.trace(
             "Handler ",
             node.value.id,
diff --git a/lua/neo-tree/defaults.lua b/lua/neo-tree/defaults.lua
@@ -393,11 +393,15 @@ local config = {
       ["<cr>"] = "open",
       -- ["<cr>"] = { "open", config = { expand_nested_files = true } }, -- expand nested file takes precedence
       ["<esc>"] = "cancel", -- close preview or floating neo-tree window
-      ["P"] = { "toggle_preview", config = {
-        use_float = true,
-        use_image_nvim = false,
-        -- title = "Neo-tree Preview", -- You can define a custom title for the preview floating window.
-      } },
+      ["P"] = {
+        "toggle_preview",
+        config = {
+          use_float = true,
+          use_snacks_image = true,
+          use_image_nvim = true,
+          -- title = "Neo-tree Preview", -- You can define a custom title for the preview floating window.
+        }
+      },
       ["<C-f>"] = { "scroll_preview", config = {direction = -10} },
       ["<C-b>"] = { "scroll_preview", config = {direction = 10} },
       ["l"] = "focus_preview",
diff --git a/lua/neo-tree/events/init.lua b/lua/neo-tree/events/init.lua
@@ -2,7 +2,7 @@ local q = require("neo-tree.events.queue")
 local log = require("neo-tree.log")
 local utils = require("neo-tree.utils")
 
----@class neotree.Event.Functions
+---@class neotree.event.Functions
 local M = {
   -- Well known event names, you can make up your own
   AFTER_RENDER = "after_render",
@@ -31,6 +31,7 @@ local M = {
   NEO_TREE_WINDOW_AFTER_OPEN = "neo_tree_window_after_open",
   NEO_TREE_WINDOW_BEFORE_CLOSE = "neo_tree_window_before_close",
   NEO_TREE_WINDOW_BEFORE_OPEN = "neo_tree_window_before_open",
+  NEO_TREE_PREVIEW_BEFORE_RENDER = "neo_tree_preview_before_render",
   VIM_AFTER_SESSION_LOAD = "vim_after_session_load",
   VIM_BUFFER_ADDED = "vim_buffer_added",
   VIM_BUFFER_CHANGED = "vim_buffer_changed",
@@ -60,7 +61,7 @@ local parse_autocmd_string = function(autocmds)
   return parsed[1], parsed[2]
 end
 
----@param event_name neotree.Event|string
+---@param event_name neotree.EventName|string
 ---@param autocmds string[]
 ---@param debounce_frequency integer?
 ---@param seed_fn function?
@@ -79,7 +80,7 @@ M.define_autocmd_event = function(event_name, autocmds, debounce_frequency, seed
           group = augroup,
           nested = nested,
           callback = function(args)
-            ---@class neotree.Event.Autocmd.CallbackArgs : neotree._vim.api.keyset.create_autocmd.callback_args
+            ---@class neotree.event.Autocmd.CallbackArgs : neotree._vim.api.keyset.create_autocmd.callback_args
             ---@field afile string
             local event_args = args --[[@as neotree._vim.api.keyset.create_autocmd.callback_args]]
             event_args.afile = args.file or ""
diff --git a/lua/neo-tree/events/queue.lua b/lua/neo-tree/events/queue.lua
@@ -2,21 +2,23 @@ local utils = require("neo-tree.utils")
 local log = require("neo-tree.log")
 local Queue = require("neo-tree.collections").Queue
 
+---@type table<string, neotree.collections.Queue?>
 local event_queues = {}
+---@type table <string, neotree.event.Definition?>
 local event_definitions = {}
 local M = {}
 
----@class neotree.Event.Handler.Result
+---@class neotree.event.Handler.Result
 ---@field handled boolean?
 
----@class neotree.Event.Handler
----@field event neotree.Event|string
----@field handler fun(table?):(neotree.Event.Handler.Result?)
+---@class neotree.event.Handler
+---@field event neotree.EventName|string
+---@field handler fun(table?):(neotree.event.Handler.Result?)
 ---@field id string?
 
 local typecheck = require("neo-tree.health.typecheck")
 local validate = typecheck.validate
----@param event_handler neotree.Event.Handler
+---@param event_handler neotree.event.Handler
 local validate_event_handler = function(event_handler)
   return validate("event_handler", event_handler, function(eh)
     validate("event", eh.event, "string")
@@ -31,10 +33,13 @@ M.clear_all_events = function()
   event_queues = {}
 end
 
----@class neotree.EventDefinition
+---@class neotree.event.Definition
+---@field teardown function?
+---@field setup function?
+---@field setup_was_run boolean?
 
----@param event_name string
----@param opts neotree.EventDefinition
+---@param event_name neotree.EventName|string
+---@param opts neotree.event.Definition
 M.define_event = function(event_name, opts)
   local existing = event_definitions[event_name]
   if existing ~= nil then
@@ -43,7 +48,7 @@ M.define_event = function(event_name, opts)
   event_definitions[event_name] = opts
 end
 
----@param event_name string
+---@param event_name neotree.EventName|string
 ---@return boolean existed_and_destroyed
 M.destroy_event = function(event_name)
   local existing = event_definitions[event_name]
@@ -61,7 +66,7 @@ M.destroy_event = function(event_name)
   return true
 end
 
----@param event string
+---@param event neotree.EventName|string
 ---@param args table
 local fire_event_internal = function(event, args)
   local queue = event_queues[event]
@@ -105,7 +110,7 @@ local fire_event_internal = function(event, args)
   end)
 end
 
----@param event string
+---@param event neotree.EventName|string
 ---@param args any?
 M.fire_event = function(event, args)
   local freq = utils.get_value(event_definitions, event .. ".debounce_frequency", 0, true)
@@ -120,7 +125,7 @@ M.fire_event = function(event, args)
   end
 end
 
----@param event_handler neotree.Event.Handler
+---@param event_handler neotree.event.Handler
 M.subscribe = function(event_handler)
   validate_event_handler(event_handler)
 
@@ -144,7 +149,7 @@ M.subscribe = function(event_handler)
   queue:add(event_handler)
 end
 
----@param event_handler neotree.Event.Handler
+---@param event_handler neotree.event.Handler
 M.unsubscribe = function(event_handler)
   local queue = event_queues[event_handler.event]
   if queue == nil then
diff --git a/lua/neo-tree/health/init.lua b/lua/neo-tree/health/init.lua
@@ -23,6 +23,22 @@ local function check_dependencies()
   else
     health.error("nui.nvim not installed")
   end
+
+  health.info("Optional dependencies for preview image support (only need one):")
+  -- optional
+  local snacks_ok = pcall(require, "snacks.image")
+  if snacks_ok then
+    health.ok("snacks.image is installed")
+  else
+    health.info("nui.nvim not installed")
+  end
+
+  local image_ok = pcall(require, "image")
+  if image_ok then
+    health.ok("image.nvim is installed")
+  else
+    health.info("nui.nvim not installed")
+  end
 end
 
 local validate = typecheck.validate
@@ -300,8 +316,9 @@ function M.check_config(config)
 end
 
 function M.check()
-  health.start("Neo-tree")
+  health.start("Dependencies")
   check_dependencies()
+  health.start("Configuration")
   local config = require("neo-tree").ensure_config()
   M.check_config(config)
 end
diff --git a/lua/neo-tree/sources/common/preview.lua b/lua/neo-tree/sources/common/preview.lua
diff --git a/lua/neo-tree/types/config.lua b/lua/neo-tree/types/config.lua
diff --git a/lua/neo-tree/types/events.lua b/lua/neo-tree/types/events.lua
