From ed9b8a4a1c9add4a46da241a41ac3349531c3dbc Mon Sep 17 00:00:00 2001
From: Birdee <85372418+BirdeeHub@users.noreply.github.com>
Date: Thu, 29 Aug 2024 18:13:48 -0700
Subject: [PATCH] feat(api): `handler.post_load` for setting up custom events
 (#82)

* feat(handler post_load): for setting up custom events
added a post_load callback for handlers to use to set
their own events such as DeferredUIEnter

In addition, made event handler use this feature to create DeferredUIEnter
further decoupling the handlers from the core of lz.n

* Update README.md

Co-authored-by: Marc Jakobi <mrcjkb89@outlook.com>

* Update lua/lz/n/meta.lua

Co-authored-by: Marc Jakobi <mrcjkb89@outlook.com>

---------

Co-authored-by: Marc Jakobi <mrcjkb89@outlook.com>
---
 README.md                  |  1 +
 lua/lz/n/handler/event.lua | 20 ++++++++++++++++++++
 lua/lz/n/handler/init.lua  |  9 +++++++++
 lua/lz/n/init.lua          | 18 +-----------------
 lua/lz/n/meta.lua          |  5 +++++
 5 files changed, 36 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index e4caf70..4b1bda1 100755
--- a/README.md
+++ b/README.md
@@ -401,6 +401,7 @@ require("lz.n").register_handler(handler)
 | add        | `fun(plugin: lz.n.Plugin)`        | adds a plugin to the handler                              |
 | del        | `fun(name: string)`               | removes a plugin from the handler by name                 |
 | lookup     | `fun(name: string): lz.n.Plugin?` | lookup a plugin managed by this handler by name           |
+| post_load        | `fun()?`               | ran once after each `require('lze').load` call, for handlers to create custom triggers such as the event handler's `DeferredUIEnter` event |
 <!-- markdownlint-enable MD013 -->
 
 To manage handler state safely, ensuring `trigger_load` can be invoked from
diff --git a/lua/lz/n/handler/event.lua b/lua/lz/n/handler/event.lua
index c391a01..7d381aa 100644
--- a/lua/lz/n/handler/event.lua
+++ b/lua/lz/n/handler/event.lua
@@ -178,4 +178,24 @@ end
 
 M.del = state.del
 
+local deferred_ui_enter = vim.schedule_wrap(function()
+    if vim.v.exiting ~= vim.NIL then
+        return
+    end
+    vim.g.lz_n_did_deferred_ui_enter = true
+    vim.api.nvim_exec_autocmds("User", { pattern = "DeferredUIEnter", modeline = false })
+end)
+
+function M.post_load()
+    if vim.v.vim_did_enter == 1 then
+        deferred_ui_enter()
+    elseif not vim.g.lz_n_did_create_deferred_ui_enter_autocmd then
+        vim.api.nvim_create_autocmd("UIEnter", {
+            once = true,
+            callback = deferred_ui_enter,
+        })
+        vim.g.lz_n_did_create_deferred_ui_enter_autocmd = true
+    end
+end
+
 return M
diff --git a/lua/lz/n/handler/init.lua b/lua/lz/n/handler/init.lua
index 44470ab..0214885 100644
--- a/lua/lz/n/handler/init.lua
+++ b/lua/lz/n/handler/init.lua
@@ -105,6 +105,15 @@ function M.disable(name)
     end)
 end
 
+function M.run_post_load()
+    ---@param handler lz.n.Handler
+    vim.iter(handlers):each(function(_, handler)
+        if handler.post_load then
+            handler.post_load()
+        end
+    end)
+end
+
 ---@param plugins table<string, lz.n.Plugin>
 function M.init(plugins)
     ---@param plugin lz.n.Plugin
diff --git a/lua/lz/n/init.lua b/lua/lz/n/init.lua
index c474788..fa8ea35 100644
--- a/lua/lz/n/init.lua
+++ b/lua/lz/n/init.lua
@@ -19,14 +19,6 @@ if vim.fn.has("nvim-0.10.0") ~= 1 then
     error("lz.n requires Neovim >= 0.10.0")
 end
 
-local deferred_ui_enter = vim.schedule_wrap(function()
-    if vim.v.exiting ~= vim.NIL then
-        return
-    end
-    vim.g.lz_n_did_deferred_ui_enter = true
-    vim.api.nvim_exec_autocmds("User", { pattern = "DeferredUIEnter", modeline = false })
-end)
-
 --- The function provides two overloads, each suited for different use cases:
 ---
 ---@overload fun(plugin: lz.n.Plugin)
@@ -82,15 +74,7 @@ function M.load(spec)
     -- `require('lz.n').trigger_load()` safely
     require("lz.n.loader").load_startup_plugins(plugins)
 
-    if vim.v.vim_did_enter == 1 then
-        deferred_ui_enter()
-    elseif not vim.g.lz_n_did_create_deferred_ui_enter_autocmd then
-        vim.api.nvim_create_autocmd("UIEnter", {
-            once = true,
-            callback = deferred_ui_enter,
-        })
-        vim.g.lz_n_did_create_deferred_ui_enter_autocmd = true
-    end
+    require("lz.n.handler").run_post_load()
 end
 
 --- Lookup a plugin that is pending to be loaded by name.
diff --git a/lua/lz/n/meta.lua b/lua/lz/n/meta.lua
index eb76e73..25e53f9 100644
--- a/lua/lz/n/meta.lua
+++ b/lua/lz/n/meta.lua
@@ -102,6 +102,11 @@
 ---
 --- Lookup a plugin by name.
 ---@field lookup fun(name: string): lz.n.Plugin?
+---
+---For setting up handler specific triggers such as
+---the `DeferredUIEnter` event created by the builtin
+---event handler. Called once after each call to require("lz.n").load
+---@field post_load? fun()
 
 ---@type lz.n.Config
 vim.g.lz_n = vim.g.lz_n