doomemacs/modules/completion/selectrum/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.
- selectrum 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 selectrum 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.
** TODO Consider dropping prescient flag
The only advantage over orderless is frecency over recency, without the better
integration orderless has with built in emacs completion. A compromise might be
to have ~+prescient~ just add prescient sorting, but it's probably not worth the
maintenance burden.
** TODO =SPC s s= and =SPC s S= ~:sw~ ?
There isn't really a selectrum 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=
Selectrum/Consult don't have a ~swiper-all~ analogue either. Unbound for now.
** TODO Orderless 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 =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 Consider renaming the module
=:completion selectrum= is a bit of a misnomer. Selectrum is probably the
most easily replaceable part of the module as it can replaced with Vertico
fairly easily, other than losing the ~selectrum-repeat~ command. However,
naming is hard™. Best alternative I can think of is this:
#+begin_src emacs-lisp
:completion
;...
;ivy           ;; a search engine for love and life
compleseus     ;; a search engine with all the planks replaced
#+end_src
** TODO Consider dropping Selectrum in favor of Vertico:
To this end there is currently a ~+vertico~ flag to try it out, weird naming
aside. I want to do this for a few reasons:
*** Selectrum is more buggy
Selectrum has a few longstanding bugs that don't exist in Vertico, namely: [[https://github.com/raxod502/selectrum/issues/491][491]]
and [[https://github.com/raxod502/selectrum/issues/561][561]], as well as having worse handling when having lines of varying height
(important for good icon support).
*** Feature Comparison
- Minad, Vertico's author, provides a detailed comparison [[https://github.com/hlissner/doom-emacs/pull/4664#issuecomment-871524782][here]]. I will note
  however that I was seriously considering the switch before he wrote this
  comparison due to the frustration of dealing with the rough edges.
- Vertico doesn't support prescient, but I want to drop it anyway.
- The [[https://github.com/raxod502/selectrum#vertico][feature comparison]] in the selectrum readme has been updated to better
  reflect the current state of affairs. Both Vertico and Selectrum have some
  features that the other package lacks. In my mind Vertico's features are more
  useful, but the feature difference is small enough for it to be less important
  than the bugginess imo.
*** Vertico is more actively maintained
This might be a temporary concern, but still.
** TODO Icon support
The icon support works well enough when using Vertico, but is a bit dodgy on
Selectrum due to it not handling lines of varying height that well, which ends
up causing the selection to slide off the screen when moving it the to the
bottom in some cases. Hopefully we just use Vertico and this becomes a nonissue,
but it should still be taken into account.

* PROJ HACKs to be addressed
** 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 selectrum 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 Review blocking Issues
** TODO Embark export window buffer switching logic
*** DONE ~grep~
The clicking links exported grep buffers used to open in a new window, but now
  open in another window. Caused by the ~set-popup-rule!~ entries for the embark
  export/collect buffers. These don't seem to serve much of a purpose at this
  point so they have been removed.
*** TODO Open upstream Embark issue for ~bookmark~ and ~file~
~bookmark~ or ~file~ export buffers open the links in the same window rather than
the other one. This can be reproduces on emacs -Q.
This is due to orderless adding a bunch of other matches.

* PROJ Review non-blocking Issues
** TODO Profile selectrum =SPC /= vs ivy =SPC /=
Check if there are other places where optimisations can be made. Perhaps the
~command-input-async~ variables can tolorate lower values.
** TODO ~(defadvice! +orderless-match-with-one-face..~ causes lexical error
Probably caused by some doomism

https://github.com/oantolin/orderless/issues/41

* PROJ Upstream Issues
** TODO Selectrum separators cause size calculation bug
https://github.com/raxod502/selectrum/issues/491
** TODO ~selectrum-repeat~ doesn't scroll to previously selected candidate
Unlike Ivy, ~selectrum-repeat~ doesn't restore the position of the selection in
the completion buffer. Seems to be reproduced in ~emacs -Q~. If so, create
upstream selectrum issue.
** TODO Marginalia annotations sometimes disappear on ~find-file~
https://github.com/raxod502/selectrum/issues/561

* 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~.