eshell: align the arrows in the output of "j -l"HEADmaster

* eshell-conf.el (eshell/j): Update the usage text to the new format.

(eshell-j-recent-label): New face for the label of recent directories.

(eshell-j-space-with-width, eshell-j-width): Functions to work with
strings, in pixels on graphical displays and in columns otherwise.

(eshell-j): When listing candidates, print every item as
"DISPLAY -> PATH"
with the arrows aligned at the same column.  Recent directories now
have the label "RECENT", and claude sessions use
"TITLE -> PATH"
instead of "TITLE: PATH".
The mark directory itself is labelled "marks".

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

1 files changed, 76 insertions, 23 deletions

diff --git a/eshell-conf.el b/eshell-conf.el
index 7b226e1..4e1ff05 100644
--- a/eshell-conf.el
+++ b/eshell-conf.el
@@ -259,10 +259,12 @@ ARGS."
      (?h "help" nil nil "Print this help message.")
      :usage "[-hmrsal] [short-cut]"
      :post-usage "Without any of [-mrsa], only marks are the sources.
-For listing candidates, the style of a line is determiney by the source:
-\"NAME -> PATH\" for a mark,
-\"PATH\" for a recent directory, and
-\"TITLE: PATH\" for a claude session.")
+For listing candidates, the style of a line is determined by the source:
+\"NAME   -> PATH\" for a mark,
+\"RECENT -> PATH\" for a recent directory, and
+\"TITLE  -> PATH\" for a claude session.
+
+The arrows are aligned at the same column.")
    (eshell-j
     args
     (cond
@@ -274,6 +276,12 @@ For listing candidates, the style of a line is determiney by the source:
      ((list 'marks)))
     list-p)))
 
+(defface eshell-j-recent-label
+  '((((background dark)) :foreground "salmon")
+    (t :foreground "firebrick"))
+  "Face for the display of labels of recent directories in the output of
+`eshell-j'.")
+
 (defface eshell-j-mark-name
   '((((background dark)) :foreground "sky blue")
     (t :foreground "DeepSkyBlue4"))
@@ -366,6 +374,26 @@ supposed to leave the global state alone as well.
 
 (load-file "~/scripts/claude/claude-session.el")
 
+(defun eshell-j-space-with-width (width)
+  "Return a string with width WIDTH.
+If we are using a graphics display, the width should be in pixels, and
+the returned string will have exactly that as the pixel width; otherwise
+the width is the number of spaces to be included in the returned string."
+  (cond
+   ((display-graphic-p)
+    (propertize
+     (string 32)
+     'display (list 'space :width (list width))))
+   ((make-string width 32))))
+
+(defun eshell-j-width (str)
+  "Return the width of STR.
+If we are using a graphics display, use `string-pixel-width'; otherwise
+use `string-width'."
+  (cond
+   ((display-graphic-p) (string-pixel-width str))
+   ((string-width str))))
+
 ;;;###autoload
 (defun eshell-j (&optional short-cut sources list-p)
   "Jump to SHORT-CUT, or list the candidates if LIST-P is non-nil.
@@ -388,9 +416,11 @@ directly; otherwise use `completing-read' to choose one destination.
 If LIST-P is non-nil, return a string listing one line for one
 candidate, in the following format:
 
-\"NAME -> PATH\" for a mark,
-\"PATH\" for a recent directory, and
-\"TITLE: PATH\" for a claude session."
+\"NAME   -> PATH\" for a mark,
+\"RECENT -> PATH\" for a recent directory, and
+\"TITLE  -> PATH\" for a claude session.
+
+The arrows are aligned at the same column."
   (let* ((accepted-sources (list 'marks 'recent 'session))
          ;; filter out unknown source symbols.
          (sources (delq
@@ -436,7 +466,7 @@ candidate, in the following format:
                (cond
                 ((string-match-p short-cut mark-directory)
                  (cons
-                  (cons mark-directory mark-directory)
+                  (cons "marks" mark-directory)
                   nil))))))))
          (recent
           (cond
@@ -468,21 +498,44 @@ candidate, in the following format:
      ((null candidates)
       (user-error "No candidates matching %s found" short-cut))
      (list-p
-      (concat
-       (mapconcat
-        (lambda (cand)
-          (concat
-           (car cand)
-           " -> "
-           (file-truename (cdr cand))
-           "\n"))
-        marks "")
-       (mapconcat
-        (lambda (cand) (concat (car cand) "\n"))
-        recent "")
-       (mapconcat
-        (lambda (cand) (concat (car cand) "\n"))
-        sessions "")))
+      (let* ((recent-label
+              (propertize "RECENT" 'face 'eshell-j-recent-label))
+             (rows
+              (append
+               (mapcar
+                (lambda (cand)
+                  (cons (car cand) (file-truename (cdr cand))))
+                marks)
+               (mapcar
+                (lambda (cand)
+                  (cons recent-label (cdr cand)))
+                recent)
+               ;; strip the ": DIR" suffix to get the title.
+               (mapcar
+                (lambda (cand)
+                  (cons
+                   (substring
+                    (car cand)
+                    0 (- (length (car cand))
+                         (length (cdr cand))
+                         2))
+                   (cdr cand)))
+                sessions)))
+             (max-width
+              (apply
+               #'max
+               3                        ; a default minimum width
+               (mapcar
+                (lambda (item) (eshell-j-width (car item)))
+                rows))))
+        (mapconcat
+         (lambda (row)
+           (concat
+            (car row)
+            (eshell-j-space-with-width
+             (- max-width (eshell-j-width (car row))))
+            " -> " (cdr row) "\n"))
+         rows "")))
      ;; jump if only one destination is present
      ((null
        (cdr