feat(pick)!: set custom vim.ui.select implementation

echasnovski · echasnovski · commit a447cccd085a · 2025-09-16T15:38:33.000+03:00
Details:
- This is a breaking change only if user didn't opt-in for
  `vim.ui.select` from 'mini.pick'. Either deliberately (which hopefully
  should be rare) or unknowingly (which this change should resolve).
  It can still be explicitly opted out by manually setting
  `vim.ui.select` *after* `require('mini.pick').setup()`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,15 @@ There are following change types:
 
     This change is made to improve long term project stability. See more details [here](https://github.com/nvim-mini/mini.nvim/discussions/1970).
 
+- Start setting custom Neovim method implementation during `setup()` (if module provides one). This is usually the expected behavior for majority of use cases and should improve "out of the box" experience. Modules should still export a function to manually adjust the implementation.
+
+    It is a breaking change only if the implementation was not explicitly used. Can still be done if set or restored *after* calling module's `setup()`.
+
+    Affected modules:
+
+    - 'mini.notify' sets `vim.notify`.
+    - 'mini.pick' sets `vim.ui.select`.
+
 ### Refine
 
 - Stop official support of Neovim 0.8.
@@ -115,14 +124,6 @@ There are following change types:
 
 - Update `zoom()` to return whether current buffer is zoomed in. By @loichyan, PR #1954.
 
-## mini.notify
-
-### Evolve
-
-- Update `setup()` to set `vim.notify` to a custom implementation, which is arguably the expected behavior for majority of use cases. This makes it unnecessary to manually `vim.notify = MiniNotify.make_notify()` after the `setup()`, but still can be done to adjust the behavior with custom options.
-
-    This is a breaking change for users who do not use 'mini.notify' for `vim.notify` implementation. To keep doing that, set `vim.notify` *after* executing `require('mini.notify').setup()`.
-
 ## mini.pick
 
 ### Expand
diff --git a/doc/mini-pick.txt b/doc/mini-pick.txt
@@ -25,7 +25,8 @@ Features:
 
 - |:Pick| command to work with extensible |MiniPick.registry|.
 
-- |vim.ui.select()| wrapper (see |MiniPick.ui_select()|).
+- |vim.ui.select()| implementation. To adjust, use |MiniPick.ui_select()|
+  or save-restore `vim.ui.select` manually after calling |MiniPick.setup()|.
 
 - Rich and customizable built-in |MiniPick-actions| when picker is active:
     - Manually change currently focused item.
@@ -684,6 +685,10 @@ Example: >vim
   :Pick files tool='git'
   :Pick grep pattern='<cword>'
 <
+
+It also sets custom |vim.ui.select()| implementation to use the module.
+See |MiniPick.ui_select()|.
+
 Parameters ~
 {config} `(table|nil)` Module config table. See |MiniPick.config|.
 
@@ -1056,6 +1061,7 @@ Select rewrite
 
 Function which can be used to directly override |vim.ui.select()| to use
 'mini.pick' for any "select" type of tasks.
+Set automatically in |MiniPick.setup()|.
 
 Implements required by `vim.ui.select()` signature, with some differencies:
 - Allows `opts.preview_item` that returns an array of lines for item preview.
@@ -1066,14 +1072,18 @@ Notes:
 
 Usage ~
 >lua
-  vim.ui.select = MiniPick.ui_select
-
   -- Customize with fourth argument inside a function wrapper
   vim.ui.select = function(items, opts, on_choice)
     local start_opts = { window = { config = { width = vim.o.columns } } }
     return MiniPick.ui_select(items, opts, on_choice, start_opts)
   end
 <
+To preserve original `vim.ui.select()`: >lua
+
+  local ui_select_orig = vim.ui.select
+  require('mini.pick').setup()
+  vim.ui.select = ui_select_orig
+<
 ------------------------------------------------------------------------------
                                                               *MiniPick.builtin*
                                `MiniPick.builtin`
diff --git a/lua/mini/pick.lua b/lua/mini/pick.lua
@@ -25,7 +25,8 @@
 ---
 --- - |:Pick| command to work with extensible |MiniPick.registry|.
 ---
---- - |vim.ui.select()| wrapper (see |MiniPick.ui_select()|).
+--- - |vim.ui.select()| implementation. To adjust, use |MiniPick.ui_select()|
+---   or save-restore `vim.ui.select` manually after calling |MiniPick.setup()|.
 ---
 --- - Rich and customizable built-in |MiniPick-actions| when picker is active:
 ---     - Manually change currently focused item.
@@ -694,6 +695,10 @@ local H = {}
 ---   :Pick files tool='git'
 ---   :Pick grep pattern='<cword>'
 --- <
+---
+--- It also sets custom |vim.ui.select()| implementation to use the module.
+--- See |MiniPick.ui_select()|.
+---
 ---@param config table|nil Module config table. See |MiniPick.config|.
 ---
 ---@usage >lua
@@ -726,6 +731,9 @@ MiniPick.setup = function(config)
     if not MiniPick.is_picker_active() then return paste_orig(...) end
     H.notify('Use `mappings.paste` (`<C-r>` by default) with "*" or "+" register.', 'HINT')
   end
+
+  -- Set custom implementation
+  vim.ui.select = MiniPick.ui_select
 end
 
 --stylua: ignore
@@ -1228,6 +1236,7 @@ end
 ---
 --- Function which can be used to directly override |vim.ui.select()| to use
 --- 'mini.pick' for any "select" type of tasks.
+--- Set automatically in |MiniPick.setup()|.
 ---
 --- Implements required by `vim.ui.select()` signature, with some differencies:
 --- - Allows `opts.preview_item` that returns an array of lines for item preview.
@@ -1237,14 +1246,18 @@ end
 --- - `on_choice` is called when target window is current.
 ---
 ---@usage >lua
----   vim.ui.select = MiniPick.ui_select
----
 ---   -- Customize with fourth argument inside a function wrapper
 ---   vim.ui.select = function(items, opts, on_choice)
 ---     local start_opts = { window = { config = { width = vim.o.columns } } }
 ---     return MiniPick.ui_select(items, opts, on_choice, start_opts)
 ---   end
 --- <
+--- To preserve original `vim.ui.select()`: >lua
+---
+---   local ui_select_orig = vim.ui.select
+---   require('mini.pick').setup()
+---   vim.ui.select = ui_select_orig
+--- <
 MiniPick.ui_select = function(items, opts, on_choice, start_opts)
   local format_item = opts.format_item or H.item_to_string
   local items_ext = {}
diff --git a/readmes/mini-pick.md b/readmes/mini-pick.md
@@ -41,7 +41,7 @@ https://github.com/nvim-mini/mini.nvim/assets/24854248/65849d1e-3f96-4085-a4cf-f
 
 - `:Pick` command to work with extensible `MiniPick.registry`.
 
-- `vim.ui.select()` wrapper.
+- `vim.ui.select()` implementation. To adjust, use `MiniPick.ui_select()` or save-restore `vim.ui.select` manually after calling `MiniPick.setup()`.
 
 - Rich and customizable built-in actions when picker is active:
     - Manually change currently focused item.
diff --git a/tests/test_pick.lua b/tests/test_pick.lua
@@ -260,6 +260,10 @@ T['setup()']['creates side effects'] = function()
   validate_hl_group('MiniPickPrompt', 'links to DiagnosticFloatingInfo')
   validate_hl_group('MiniPickPromptCaret', 'links to MiniPickPrompt')
   validate_hl_group('MiniPickPromptPrefix', 'links to MiniPickPrompt')
+
+  -- `vim.ui.select` implementation
+  child.lua_notify('vim.ui.select({ "a", "b" }, {}, function() end)')
+  eq(child.lua_get('MiniPick.get_picker_items() ~= nil'), true)
 end
 
 T['setup()']['creates `config` field'] = function()
