[elpa] externals/transient e90f7a165e 335/366: Add support for returning from a sub-prefix to the parent prefix

[Jonas Bernoulli]

branch: externals/transient
commit e90f7a165e05b80846781823d23e8b078d4bb142
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>

    Add support for returning from a sub-prefix to the parent prefix
---
 docs/transient.org | 35 +++++++++++++++++++++++++++++++++--
 lisp/transient.el  | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/docs/transient.org b/docs/transient.org
index 798c27dd46..7cf0c6a95d 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -1193,16 +1193,47 @@ The default for suffixes is ~transient--do-exit~.
 
   Call the command after exporting variables and exit the transient.
 
+- Function: transient--do-return ::
+
+  Call the command after exporting variables and return to parent
+  prefix.  If there is no parent prefix, then call ~transient--do-exit~.
+
 - Function: transient--do-call ::
 
   Call the command after exporting variables and stay transient.
 
+The following pre-commands are suitable for sub-prefixes.  Only the
+first should ever explicitly be set as the value of the ~transient~
+slot.
+
+- Function: transient--do-recurse ::
+
+  Call the transient prefix command, preparing for return to active
+  transient.
+
+  Whether we actually return to the parent transient is ultimately
+  under the control of each invoked suffix.  The difference between
+  this pre-command and ~transient--do-replace~ is that it changes the
+  value of the ~transient-suffix~ slot to ~transient--do-return~.
+
+  If there is no parent transient, then only call this command and
+  skip the second step.
+
 - Function: transient--do-replace ::
 
   Call the transient prefix command, replacing the active transient.
 
-  This is used for suffixes that are prefixes themselves, i.e. for
-  sub-prefixes.
+  Unless ~transient--do-recurse~ is explicitly used, this pre-command
+  is automatically used for suffixes that are prefixes themselves,
+  i.e. for sub-prefixes.
+
+- Function: transient--do-suspend ::
+
+  Suspend the active transient, saving the transient stack.
+
+  This is used by the command ~transient-suspend~ and optionally also by
+  "external events" such as ~handle-switch-frame~.  Such bindings should
+  be added to ~transient-predicate-map~.
 
 *** Pre-commands for Non-Suffixes
 :PROPERTIES:
diff --git a/lisp/transient.el b/lisp/transient.el
index 9addbafa4c..1b1e53400a 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -524,6 +524,15 @@ These faces are only used if `transient-semantic-coloring'
   "Face used for teal prefixes."
   :group 'transient-color-faces)
 
+(defface transient-purple
+  '((t :inherit transient-key :foreground "#a020f0"))
+  "Face used for purple prefixes.
+
+This is an addition to the colors supported by Hydra.  It is
+used by suffixes that quit the current prefix but return to
+the previous prefix."
+  :group 'transient-color-faces)
+
 ;;; Persistence
 
 (defun transient--read-file-contents (file)
@@ -1760,6 +1769,7 @@ value.  Otherwise return CHILDREN as is."
                       :level (or (alist-get t (alist-get name 
transient-levels))
                                  transient-default-level)
                       params))))
+    (transient--setup-recursion obj)
     (transient-init-value obj)
     obj))
 
@@ -2235,12 +2245,34 @@ nil) then do nothing."
   (transient--export)
   transient--stay)
 
+(defun transient--do-return ()
+  "Call the command after exporting variables and return to parent prefix.
+If there is no parent prefix, then behave like `transient--do-exit'."
+  (if (not transient--stack)
+      (transient--do-exit)
+    (transient--export)
+    transient--exit))
+
 (defun transient--do-exit ()
   "Call the command after exporting variables and exit the transient."
   (transient--export)
   (transient--stack-zap)
   transient--exit)
 
+(defun transient--do-recurse ()
+  "Call the transient prefix command, preparing for return to active transient.
+If there is no parent prefix, then just call the command."
+  (transient--do-replace))
+
+(defun transient--setup-recursion (prefix-obj)
+  (when transient--stack
+    (let ((command (oref prefix-obj command)))
+      (when-let ((suffix-obj (transient-suffix-object command)))
+        (when (and (slot-boundp suffix-obj 'transient)
+                   (eq (oref suffix-obj transient)
+                       'transient--do-recurse))
+          (oset prefix-obj transient-suffix 'transient--do-return))))))
+
 (defun transient--do-replace ()
   "Call the transient prefix command, replacing the active transient."
   (transient--export)
@@ -2283,7 +2315,9 @@ to `transient--do-warn'."
 (put 'transient--do-warn       'transient-color 'transient-red)
 (put 'transient--do-warn-inapt 'transient-color 'transient-red)
 (put 'transient--do-call       'transient-color 'transient-red)
+(put 'transient--do-return     'transient-color 'transient-purple)
 (put 'transient--do-exit       'transient-color 'transient-blue)
+(put 'transient--do-recurse    'transient-color 'transient-red)
 (put 'transient--do-replace    'transient-color 'transient-blue)
 (put 'transient--do-suspend    'transient-color 'transient-blue)
 (put 'transient--do-quit-one   'transient-color 'transient-blue)
@@ -3703,6 +3737,7 @@ search instead."
                        'transient-red
                      'transient-blue))))
     (pcase (list suffix nonsuf)
+      (`(transient-purple ,_)           'transient-purple)
       (`(transient-red  disallow)       'transient-amaranth)
       (`(transient-blue disallow)       'transient-teal)
       (`(transient-red  transient-red)  'transient-pink)