API: more stracture and pass callback to all provided APIs

[neo451]

obsidian-nvim/obsidian.nvim#364 there's this issue in my repo that has been there a while, and I visit this repo from time to time to see if live grep has landed, and i found it has got it today, so I went ahead trying to integrate this plugin

but I do find the implementations a bit weird and very limited, I get the fact that this set out as a file picker, but passing a callback is just the most natural thing, and there's a open_with_callback but that is not what drives the main APIs like find_files and live_grep

API-wise, after not finding a clear API guide in the readme, I just grep these calls I want to make in your repo, but finding these are still not enough for my needs, since there's no really types in the opts param, just a table, I had to further trace the next level of functions that they calls. that really is not ideal for a repo that seems mature with many users.

and the type annotations I found is just simply wrong: https://github.com/dmtrKovalenko/fff.nvim/blob/9bc928db65be91a4c580d5ca8d1844ad9901d24c/lua/fff/picker_ui.lua#L2488-L2488

typing opts like this is just not valid type annotation for either lua-ls or emmylua-ls, it is just helping no one sitting there, seems too big of a mistake to have just sit around in such an active repo for 4 months

ok after this I found even more recent similar styled annotations, so maybe @dmtrKovalenko prefers this, but aren't you getting any diagnostics? and it is just not easy for others to call your code like this

[dmtrKovalenko]

Oh yeah I don’t use any lua lsp and type diagnostics are just generated by LLM when I asked it to lool

I probably should revisit the way docs are done. But it’s unclear what is missing concurrently? I made open with callback to support one specific use case, what are you trying to do?

[dmtrKovalenko]

https://github.com/dmtrKovalenko/fff.nvim/blob/9bc928db65be91a4c580d5ca8d1844ad9901d24c/lua/fff/main.lua

This is btw the main file

[neo451]

this is how people integrate pickers, using obsidian.nvim's snacks integration as an example:

---@param opts obsidian.PickerFindOpts|? Options.
M.find_files = function(opts)
  opts = opts or {}
  opts.callback = opts.callback or obsidian.api.open_note

  ---@type obsidian.Path
  local dir = opts.dir.filename and Path.new(opts.dir.filename) or Obsidian.dir

  local map = vim.tbl_deep_extend("force", {}, notes_mappings(opts.selection_mappings))

  local args = search.build_find_cmd()
  local cmd = table.remove(args, 1)

  local pick_opts = vim.tbl_extend("force", map or {}, {
    pattern = opts.query,
    source = "files",
    title = opts.prompt_title,
    cwd = tostring(dir),
    cmd = cmd,
    args = args,
    confirm = function(picker, item)
      picker:close()
      if item then
        opts.callback(item._path)
      end
    end,
  })
  snacks_picker.pick(pick_opts)
end

---@param opts obsidian.PickerGrepOpts|? Options.
M.grep = function(opts)
  opts = opts or {}

  ---@type obsidian.Path
  local dir = opts.dir.filename and Path.new(opts.dir.filename) or Obsidian.dir

  local map = vim.tbl_deep_extend("force", {}, notes_mappings(opts.selection_mappings))

  local args = search.build_grep_cmd()
  local cmd = table.remove(args, 1)

  local pick_opts = vim.tbl_extend("force", map or {}, {
    search = opts.query,
    source = "grep",
    title = opts.prompt_title,
    cwd = tostring(dir),
    cmd = cmd,
    args = args,
    confirm = function(picker, item, action)
      picker:close()
      if item then
        if opts.callback then
          opts.callback {
            filename = item._path or item.filename,
            col = item.pos and item.pos[2],
            lnum = item.pos and item.pos[1],
            user_data = item.value,
          }
        else
          snacks_picker.actions.jump(picker, item, action)
        end
      end
    end,
  })
  snacks_picker.pick(pick_opts)
end

key thing is the confirm field, and mini.pick calls it choose and basically what vim.ui.select has for last argument on_choice, by default your implementation is to goto the file for find_files, goto the file and specific col and line for live_grep, but user should be able to override it, for example obsidian.nvim have templating stuff, and picking a specific templete file does not mean navigate to them, but to execute a bunch other stuff in the callback, you just pass whatever is selected to it

[gustav-fff]

[triage-bot] LINKED PR: #503 (open) — #503

Adds custom on_submit handler configuration, exposing callback-driven flow for the main APIs instead of only open_with_callback. Addresses callback-passing concern raised here. Type annotation cleanup not in scope of this PR.