Subject: Re: bug#59486: completion-auto-wrap disobeyed by vertical navigation

From: Juri Linkov <[email-masked]>
Date: Thu, 02 Nov 2023 19:14:00 +0200

>> +(defcustom minibuffer-completion-visible t
>> +  "Non-nil means to navigate completions with arrows from the minibuffer.
>> +This has effect only when the window with the *Completions* buffer
>> +is visible on the screen."
>
> This doc string needs to be improved, as it currently doesn't explain
> its effect in enough detail, IMO.  Maybe because "non-nil means to
> navigate" is awkward/confusing English.

Now improved in a new patch.

> Regarding the last sentence of the doc string: does it mean that if
> the *Completions* buffer is not in any window, the arrow keys in the
> minibuffer will not move point in that buffer?

If the *Completions* buffer is not in any window, the arrow keys
move point in the minibuffer.  Now explained this in the docstring.

>> +(defun minibuffer-bind-visible (binding)
>> +  `(menu-item
>> +    "" ,binding
>> +    :filter ,(lambda (cmd)
>> +               (when (get-buffer-window "*Completions*" 0)
>> +                 cmd))))
>
> This function needs a doc string and possibly a better name, to match
> what it actually does.

Done.

> The argument zero to get-buffer-window AFAIU means that it will return
> non-nil when the buffer is shown in some window on an iconified frame,
> and I wonder why we would consider such a buffer "visible".

(get-buffer-window "*Completions*" 0) is used everywhere in minibuffer.el
and simple.el, so the argument zero is for compatibility with other
minibuffer completion commands.

>> +  "RET"     (minibuffer-bind-visible #'minibuffer-choose-completion)
>
> AFAICT, this important binding is not mentioned or hinted in the doc
> string of the new option.

Now mentioned.

>> -(defun minibuffer-next-completion (&optional n)
>> +(defun minibuffer-next-completion (&optional n vertical)
>>    "Move to the next item in its completions window from the minibuffer.
>> +When the optional argument VERTICAL is non-nil, move vertically.
>
> The "move vertically" part contradicts the "to the next item" part,
> doesn't it?

The next item can be on the axis x or y.

> Thus, I think the added sentence should be more detailed,
> and should explicitly say that the result will be a move to the next
> line, not the next item (and perhaps also include a link to
> next-line-completion).

Ok, improved with a link.

>> +(defun minibuffer-next-line-completion (&optional n)
>> +  "Move to the next completion line from the minibuffer.
>
> This sentence is misleading, IMO.  Assuming I understood what you
> mean, I would rephrase:
>
>   Move to the completion candidate on the next line in the completions buffer.

This line is too long and doesn't mention the minibuffer.
So I added it to the rest of the docstring.

>> +When `minibuffer-completion-auto-choose' is non-nil, then also
>> +insert the selected completion to the minibuffer."
>
> Please make a habit of talking about "completion candidate" in these
> cases, not about "completion".  The latter is ambiguous, since it can
> refer both to a candidate and to the action of performing completion.

Ok, fixed.

>> +(defun minibuffer-previous-line-completion (&optional n)
>> +  "Move to the previous completion line from the minibuffer.
>> +When `minibuffer-completion-auto-choose' is non-nil, then also
>> +insert the selected completion to the minibuffer."
>
> Same here.

Here is a new patch:

diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 2120e31775e..56ba7e235f2 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -2707,8 +2716,14 @@ completion-in-region-mode
 	  completion-in-region-mode-predicate)
     (setq-local minibuffer-completion-auto-choose nil)
     (add-hook 'post-command-hook #'completion-in-region--postch)
-    (push `(completion-in-region-mode . ,completion-in-region-mode-map)
-          minor-mode-overriding-map-alist)))
+    (let* ((keymap completion-in-region-mode-map)
+           (keymap (if minibuffer-visible-completions
+                       (make-composed-keymap
+                        (list minibuffer-visible-completions-map
+                              keymap))
+                     keymap)))
+      (push `(completion-in-region-mode . ,keymap)
+            minor-mode-overriding-map-alist))))
 
 ;; Define-minor-mode added our keymap to minor-mode-map-alist, but we want it
 ;; on minor-mode-overriding-map-alist instead.
@@ -2953,7 +2972,41 @@ minibuffer-mode
   :interactive nil
   ;; Enable text conversion, but always make sure `RET' does
   ;; something.
-  (setq text-conversion-style 'action))
+  (setq text-conversion-style 'action)
+  (when minibuffer-visible-completions
+    (setq-local minibuffer-completion-auto-choose nil)))
+
+(defcustom minibuffer-visible-completions t
+  "When non-nil, visible completions can be navigated from the minibuffer.
+This means that when the *Completions* buffer is visible in a window,
+then you can use the arrow keys in the minibuffer to move the cursor
+in the *Completions* buffer.  Then you can type `RET',
+and the candidate highlighted the *Completions* buffer
+will be accepted.
+But when the *Completions* buffer is not displayed on the screen,
+then the arrow keys move point in the minibuffer as usual, and
+`RET' accepts the input typed in the minibuffer."
+  :type 'boolean
+  :version "30.1")
+
+(defun minibuffer-visible-completions-bind (binding)
+  "Use BINDING when completions are visible.
+Return an item that is enabled only when a window
+displaying the *Completions* buffer exists."
+  `(menu-item
+    "" ,binding
+    :filter ,(lambda (cmd)
+               (when (get-buffer-window "*Completions*" 0)
+                 cmd))))
+
+(defvar-keymap minibuffer-visible-completions-map
+  :doc "Local keymap for minibuffer input with visible completions."
+  "<left>"  (minibuffer-visible-completions-bind #'minibuffer-previous-completion)
+  "<right>" (minibuffer-visible-completions-bind #'minibuffer-next-completion)
+  "<up>"    (minibuffer-visible-completions-bind #'minibuffer-previous-line-completion)
+  "<down>"  (minibuffer-visible-completions-bind #'minibuffer-next-line-completion)
+  "RET"     (minibuffer-visible-completions-bind #'minibuffer-choose-completion)
+  "C-g"     (minibuffer-visible-completions-bind #'minibuffer-hide-completions))
 
 ;;; Completion tables.
 
@@ -4370,6 +4423,11 @@ completing-read-default
                     ;; in minibuffer-local-filename-completion-map can
                     ;; override bindings in base-keymap.
                     base-keymap)))
+         (keymap (if minibuffer-visible-completions
+                     (make-composed-keymap
+                      (list minibuffer-visible-completions-map
+                            keymap))
+                   keymap))
          (buffer (current-buffer))
          (c-i-c completion-ignore-case)
          (result
@@ -4489,16 +4547,21 @@ minibuffer-completion-auto-choose
   :type 'boolean
   :version "29.1")
 
-(defun minibuffer-next-completion (&optional n)
+(defun minibuffer-next-completion (&optional n vertical)
   "Move to the next item in its completions window from the minibuffer.
+When the optional argument VERTICAL is non-nil, move vertically
+to the next item on the next line using `next-line-completion'.
+Otherwise, move to the next item horizontally using `next-completion'.
 When `minibuffer-completion-auto-choose' is non-nil, then also
-insert the selected completion to the minibuffer."
+insert the selected completion candidate to the minibuffer."
   (interactive "p")
   (let ((auto-choose minibuffer-completion-auto-choose))
     (with-minibuffer-completions-window
       (when completions-highlight-face
         (setq-local cursor-face-highlight-nonselected-window t))
-      (next-completion (or n 1))
+      (if vertical
+          (next-line-completion (or n 1))
+        (next-completion (or n 1)))
       (when auto-choose
         (let ((completion-use-base-affixes t))
           (choose-completion nil t t))))))
@@ -4506,17 +4569,35 @@ minibuffer-next-completion
 (defun minibuffer-previous-completion (&optional n)
   "Move to the previous item in its completions window from the minibuffer.
 When `minibuffer-completion-auto-choose' is non-nil, then also
-insert the selected completion to the minibuffer."
+insert the selected completion candidate to the minibuffer."
   (interactive "p")
   (minibuffer-next-completion (- (or n 1))))
 
+(defun minibuffer-next-line-completion (&optional n)
+  "Move to the next completion line from the minibuffer.
+This means to move to the completion candidate on the next line
+in the *Completions* buffer while point stays in the minibuffer.
+When `minibuffer-completion-auto-choose' is non-nil, then also
+insert the selected completion candidate to the minibuffer."
+  (interactive "p")
+  (minibuffer-next-completion (or n 1) t))
+
+(defun minibuffer-previous-line-completion (&optional n)
+  "Move to the previous completion line from the minibuffer.
+This means to move to the completion candidate on the previous line
+in the *Completions* buffer while point stays in the minibuffer.
+When `minibuffer-completion-auto-choose' is non-nil, then also
+insert the selected completion candidate to the minibuffer."
+  (interactive "p")
+  (minibuffer-next-completion (- (or n 1)) t))
+
 (defun minibuffer-choose-completion (&optional no-exit no-quit)
   "Run `choose-completion' from the minibuffer in its completions window.
-With prefix argument NO-EXIT, insert the completion at point to the
-minibuffer, but don't exit the minibuffer.  When the prefix argument
+With prefix argument NO-EXIT, insert the completion candidate at point to
+the minibuffer, but don't exit the minibuffer.  When the prefix argument
 is not provided, then whether to exit the minibuffer depends on the value
 of `completion-no-auto-exit'.
-If NO-QUIT is non-nil, insert the completion at point to the
+If NO-QUIT is non-nil, insert the completion candidate at point to the
 minibuffer, but don't quit the completions window."
   (interactive "P")
     (with-minibuffer-completions-window