transient: add configurable delay before showing popup (#2187)

* transient: add configurable delay before showing popup

Add a configurable delay before the transient popup appears, similar
to Doom Emacs's which-key-idle-delay. The popup waits 500ms (default)
before showing; if the user completes the key sequence before the
timer fires, the popup never appears — avoiding flicker for fast
typists. Once the popup is already visible (navigating sub-menus),
subsequent keymaps show immediately.

New exported variable: lem/transient:*transient-popup-delay*
- 500 (default): 500ms delay
- 0 or nil: show immediately

* transient: document delay variables and rationale for global timer

Address code-contractor feedback:
- Expand *transient-popup-delay* docstring to describe user intent.
- Document why *transient-delay-timer* is held as global state:
  it mirrors the lifecycle of *transient-popup-window* and must be
  reachable from hide-transient and keymap-activate so a pending
  popup can be canceled regardless of which call site aborts the
  transient sequence — the contract's well-documented exception
  to the functional-style rule.

Author: theangelperalta

extensions/transient/keymap.lisp

@@ -14,10 +14,32 @@
       (*transient-always-show*
        (or keymap *root-keymap*)))))
 
+(defun show-transient-with-delay (keymap)
+  "show the transient popup for KEYMAP, either immediately or after a delay.
+if the popup is already visible (e.g. navigating sub-menus), show immediately.
+otherwise, wait *transient-popup-delay* milliseconds before showing."
+  (cancel-transient-delay-timer)
+  (let ((delay *transient-popup-delay*))
+    (if (or (null delay)
+            (<= delay 0)
+            (transient-window-alive-p))
+        ;; show immediately: no delay configured, or popup already visible (sub-menu navigation)
+        (show-transient keymap)
+        ;; delayed: start a one-shot timer
+        (let ((target-keymap keymap))
+          (setf *transient-delay-timer*
+                (start-timer
+                 (make-timer (lambda ()
+                               (let ((resolved (resolve-transient-keymap target-keymap)))
+                                 (when resolved
+                                   (show-transient resolved))))
+                             :name "transient-popup-delay")
+                 delay))))))
+
 (defmethod keymap-activate ((keymap keymap))
   (let ((resolved (resolve-transient-keymap keymap)))
     (if resolved
-        (show-transient resolved)
+        (show-transient-with-delay resolved)
         (hide-transient))))
 
 (defgeneric mode-transient-keymap (mode)

extensions/transient/popup.lisp

@@ -27,6 +27,21 @@
   nil
   "whether to always show the transient buffer. by default only keymaps that have show-p set are shown.")
 
+(defvar *transient-popup-delay*
+  500
+  "User-configurable delay in milliseconds before the transient popup appears.
+Set to 0 or nil to show immediately (no delay). Default is 500ms.
+When the user completes a key sequence faster than this delay, the
+popup never appears, avoiding flicker for fast typists.")
+
+(defvar *transient-delay-timer*
+  nil
+  "Internal timer scheduling the delayed popup display, or nil when idle.
+Held as global state to mirror the lifecycle of `*transient-popup-window*':
+both must be reachable from `hide-transient' and from any subsequent
+`keymap-activate' so the pending popup can be canceled regardless of
+which call site aborts the transient sequence.")
+
 (define-attribute transient-matched-key-attribute
   (t
    :foreground (attribute-foreground (ensure-attribute 'syntax-string-attribute))))
@@ -513,8 +528,16 @@ prefixes marked as :intermediate-p are flattened and shown with concatenated key
             (max 0 (- current *transient-horizontal-scroll-amount*))))
     (redraw-display)))
 
+(defun cancel-transient-delay-timer ()
+  "cancel any pending delayed popup timer."
+  (when (and *transient-delay-timer*
+             (not (timer-expired-p *transient-delay-timer*)))
+    (stop-timer *transient-delay-timer*))
+  (setf *transient-delay-timer* nil))
+
 (defun hide-transient ()
   "hide (delete) the transient window."
+  (cancel-transient-delay-timer)
   (when (and *transient-popup-window*
              (not (deleted-window-p *transient-popup-window*)))
     (modeline-remove-status-list 'transient-scroll-status)

extensions/transient/transient.lisp

@@ -2,6 +2,7 @@
   (:use :cl :lem)
   (:export
    :*transient-always-show*
+   :*transient-popup-delay*
    :*transient-mode-keymap*
    :define-transient
    :define-prefix