doomemacs/modules/completion/vertico/TODO.org

* PROJ Design Decisions
** TODO Bind =consult-lsp-diagnostics= to something?
** TODO Finalize =embark-act= keybindings
They are currently set to =C-;= and =<leader> a=. The motivation for this is as
follows:
*** =C-;=
Least intrusive key-chord type binding I could find. Doesn't interfere with
other keybindings for the most part (unlike =C-o= which clashes for in
minibuffer =evil-want-minibuffer= users and regular buffer evil users), with the
exception of:
- =C-;= is bound to ~flyspell-auto-correct-previous-word~. via the built in
  flyspell map.
- =C-;= is bound to ~+company/complete~ in the vanilla emacs bindings.
We could also just bind it in the minibuffer if we do end up going with the
leader key.
*** Alternative chord: =C-,=
Still has some overlaps, but perhaps less important:
- ~flyspell-goto-next-error~
- ~org-cycle-agenda-files~ has redundancy in =C-'= anyway.
It is however less convenient than =C-;=
*** =<leader> a=
Even though top level module dependant bindings are frowned upon, here is my
case for why this should be an exception:
- It provide a useful shortcut for a bunch of commands relevant to the symbol at
  point, and seems to be better at this than built in stuff, e.g. doing
  =<leader> f D= to delete a file in =eshell= doesn't work, but embark
  recognises that it's a file, so =<leader> a d= does.
- other than helping with discoverability for stuff this also allows for
  commands for things that are too niche for top level bindings, such as actions
  on ~package!~ statements and recipes or urls.
- vertico is slated to become the default completion module, which makes this
  less of an inconsistency, but I'm not sure about the performance slowdown in
  ~map!~ since that seems to be one of the main concerns.
- ~embark~ like most packages in the vertico cinematic universe can be
  installed independently, so if you find it sufficiently useful you could also
  have a stripped down version of the config in doom core that is just used for
  on-buffer actions.
*** We also might want to add keybinidngs for =embark-dwim=
** TODO =SPC s s= and =SPC s S= ~:sw~ ?
There isn't really a vertico/consult analogue to ~swiper-isearch~, ~consult-isearch~
does something else (give you previously used isearch search terms). Bound to
regular isearch for now.
** TODO =SPC s B=
Vertico/Consult don't have a ~swiper-all~ analogue either. Unbound for now.
** TODO =C-c C-e=
On ~consult-line~ this opens a ~occur-edit~ buffer, which is a more natural fit
but breaks slightly from the =C-c C-e= = =wgrep= convention.
** TODO Keep or discard =C-M-j= and =C-M-k=
Scroll up and down while previewing. Essentially shortcuts for =C-(j|k) C-SPC=.
I like having them around but I can always just add them to my private config.
** TODO Annotation Customization
Do we want to have the annotations be more like ivy? e.g.
- Have a project column in the buffer annotations and a relative path? This has
  some overlap with project narrowing =SPC b B p SPC=.
- Mark the modified/remote status of the buffer with color, on top of the
  modification column?
- Change colors in general?
** TODO Orderless
*** TODO Style dispatchers
 Currently the =!= style dispatcher is only as a prefix, due to the abundance of
 =!= final macros. In my opinion this is useful enough to break consistency.
*** TODO Completion Style on file paths
Currently we have the following completion style override for files:
#+begin_src emacs-lisp
(setq completion-category-overrides '((file (styles . (orderless partial-completion)))))
#+end_src
This means that =parital-completion= matches (basically completing word
prefixes + globbing) only get considered if there are no =orderless= matches. I
find this to be the useful order, since I only really want =partial-completion=
for the globbing, but it does mean that you lose the ability to type the first
few letters of a file and only get the files that start with that, since you get
broader orderless matching. Ivy doesn't have this distinction with prescient on,
but does seem to only show hidden files only after there are no visible ones
left, which we don't have here.

This also relates to the [[https://github.com/minad/vertico#tramp-hostname-completion][recommended settings in the vertico readme]] for remote
hostname completion somewhat. It's hard for me to figure out what's best here
because I don't have any remotes to try this out on.
*** TODO Initialisms by default/
Do we want to use =orderless+initialism= by default for some of the completion
categories? see [[https://github.com/hlissner/doom-emacs/pull/4664#discussion_r667368998
][here]]
** TODO Decide what Vertico extensions to use
Currently we only use =vertico-repeat=, and after the next bump I'll replace
~+vertico/backward-updir~ with the =vertico-directory= implementation. Do we
want to use any other ones or leave that to users?
** TODO Decide what to do with ~embark-package-map~
** TODO =SPC b B= currently displays recent files and bookmarks by default
We can have it only display buffers by setting an initial narrowing
** TODO Company completion style
Currently we advise ~company-capf--candidates~ to try the default emacs
completion styles before orderless, since trying orderless first leads to a
bunch of junk candidates. We could let the company completion style here be a
variable for mildly easy customization, and we could also use orderless but use
a custom sorting function like ~vertico-sort-length-alpha~ which has decent
results ([[https://github.com/hlissner/doom-emacs/pull/4664#discussion_r668897763][see here]]).

* PROJ HACKs that need looking over
** TODO ~fboundp~ issues
Even if the =ivy= module isn't loaded, it's packages can still get loaded by
other means, such as =lispy= requiring =counsel=. This means that the ~fboundp~
logic [[file:~/.emacs.d/modules/config/default/autoload/text.el::(cond ((fboundp 'consult-yank-pop) #'consult-yank-pop) ;;HACK see @ymarco's comment on #5013 and TODO.org][here]] (and formerly [[file:~/.emacs.d/core/autoload/projects.el::(and (bound-and-true-p ivy-mode][here]]) won't work unless the vertico option is checked
first, which is what we do for now.
** TODO ~projectile-switch-project-action~ definition
Without [[file:~/.emacs.d/modules/ui/workspaces/config.el::;; HACK?? needs review][this]] change new projects don't get opened in a new tab, but the exact
working of this whole set up are a bit opaque to me.

* PROJ Things I'd like help with
** TODO Fix ~(defadvice! +orderless-match-with-one-face..~ lexical error
[[https://github.com/oantolin/orderless/issues/41][Probably caused by some doomism]]
** TODO Embark Export/Correct popup logic
Currently when e.g. exporting a ~consult-grep~ search to a grep buffer, it just
gets exported to a new window without any special configuration with
~set-popup-rule!~. This is because using ~set-popup-rule!~ causes the links in
the grep buffer to be opened in a new window rather than the other window, which
is undesirable. However, the default window opening logic leads to the exported
buffer being opened in a right split if the emacs frame is wide, which is also
undesirable. I have not been able to figure out what about the doom popup
mechanism is causing this, I don't think it's something in ~set-popup-rule!~
directly, but something deeper in the =:ui popup=


* PROJ Things to do before the merge
** TODO Profile vertico =SPC /= vs ivy =SPC /=
Check if there are other places where optimisations can be made. Perhaps the
~command-input-async~ variables can tolerate lower values.
** TODO Better Marginalia annotations for Projectile commands (maybe upstream)
** TODO after the next bump, replace ~+vertico/backward-updir~ with ~vertico-directory~ version
** TODO bump =bibtex-actions=
** TODO Fix the duplicate candidate issue
[[https://github.com/minad/vertico/issues/69][See here.]] If this doesn't get fixed upstream by the time of the merge we should
add an override for ~read-library-name~ at least.

* PROJ Extra credit
** TODO =bibtex-actions= improvements?
Currently =SPC n b= is bound to a function, but =bibtex-actions= doesn't have a
main dispatch function like =ivy-bibtex=, rather it has a bunch of different
ones. Binding the ~bibtex-actions-map~ there would probably be better, but there
are nontrivial loading order shenanigans happening that make that not
straightforward.
** TODO Buffer switching
- =SPC b b= should switch workspace after choosing a buffer from a different one
- Universal argument for opening buffer in another window?
** TODO Ivy Parity
*** TODO =C-RET= on minibuffer?
*** TODO pass module
*** TODO ~+ivy/jump-list~ analogue
*** WAIT lookup module
- ~dash-docs~ backend (needs to be created)
- ~+lookup--online..~ functionality (needs a consult analogue of
  ~counsel-search~)
*** WAIT taskrunner module
in all likelihood requires writing ~consult-taskrunner~.