Allow PromptEditor escape fallthrough

Author: xoofx

samples/Playground/Program.cs

@@ -1,18 +1,24 @@
 using XenoAtom.Terminal;
 using XenoAtom.Terminal.UI;
+using XenoAtom.Terminal.UI.Commands;
 using XenoAtom.Terminal.UI.Controls;
+using XenoAtom.Terminal.UI.Input;
 
-State<string?> text = new("Type here");
-State<bool> exit = new(false);
+
+
+var promptEditor = new PromptEditor();
+promptEditor.EscapeBehavior(PromptEditorEscapeBehavior.CancelCompletionOnly);
+
+promptEditor.AddCommand(new Command()
+{
+    Id = "CodeAlta.Thread.ExpandPrompt.Close",
+    LabelMarkup = "Close",
+    DescriptionMarkup = "Close the large prompt editor and keep the current draft.",
+    Gesture = new KeyGesture(TerminalKey.Escape),
+    Importance = CommandImportance.Primary,
+    Execute = _ => Terminal.Title = "Hello",
+});
 
 Terminal.Run(
-    new VStack(
-        new TextBox(text),
-        new HStack(
-            "Hello this is a long element Hello this is a long element Hello this is a long element Hello this is a long element Hello this is a long element",
-            "This is another line"
-        ),
-        new TextBlock(() => $"The text typed is: {text.Value}"),
-        new Button("Exit").Click(() => exit.Value = true)
-    ),
-    onUpdate: () => exit.Value ? TerminalLoopResult.StopAndKeepVisual : TerminalLoopResult.Continue);
+    promptEditor,
+    onUpdate: () => TerminalLoopResult.Continue);

site/docs/commands.md

@@ -41,6 +41,8 @@ Notes:
 
 - For Ctrl shortcuts, prefer `TerminalChar.CtrlX` + `TerminalModifiers.Ctrl` (terminals commonly emit control characters).
 - `Gesture` and `Sequence` are mutually exclusive.
+- By default, a matched `Gesture` is consumed even if the command is currently hidden or disabled. Set
+  `ConsumesGestureWhenUnavailable = false` when a command should reserve the key only while it is active.
 
 ## Multi-stroke shortcuts (key sequences)
 

site/docs/controls/prompteditor.md

@@ -104,6 +104,16 @@ Default behavior:
 - `Tab` requests completion (unless `AcceptTab=true`).
 - `Esc` cancels completion (or cancels the prompt if no completion UI is active).
 
+If you want to reuse `Esc` for another command when completion is inactive, switch the editor to completion-only escape
+handling:
+
+```csharp
+new PromptEditor()
+    .EscapeBehavior(PromptEditorEscapeBehavior.CancelCompletionOnly);
+```
+
+With that mode, `Esc` still dismisses active completion UI, but otherwise falls through to other shortcut bindings.
+
 ## Prompt prefix
 
 `PromptEditor` renders the prompt prefix in a dedicated left column:

src/XenoAtom.Terminal.UI.Tests/PromptEditorTests.cs

@@ -4,6 +4,7 @@
 
 using System.Linq;
 using XenoAtom.Terminal;
+using XenoAtom.Terminal.UI.Commands;
 using XenoAtom.Terminal.UI.Controls;
 using XenoAtom.Terminal.UI.Hosting;
 using XenoAtom.Terminal.UI.Input;
@@ -140,6 +141,80 @@ static PromptEditorCompletion Complete(in PromptEditorCompletionRequest request)
         driver.TickUntil(() => editor.Text == "hello");
     }
 
+    [TestMethod]
+    public void PromptEditor_Escape_Cancels_By_Default()
+    {
+        var canceled = false;
+
+        var editor = new PromptEditor()
+            .Canceled((_, _) => canceled = true)
+            .AutoFocus(true);
+
+        var root = new VStack { editor };
+
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(40, 6));
+        driver.Tick();
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Escape });
+        driver.TickUntil(() => canceled);
+    }
+
+    [TestMethod]
+    public void PromptEditor_Can_Reserve_Escape_Only_While_Completion_Is_Active()
+    {
+        static PromptEditorCompletion Complete(in PromptEditorCompletionRequest request)
+            => new(
+                Handled: true,
+                Candidates: ["hello", "help"],
+                ReplaceStart: 0,
+                ReplaceLength: request.CaretIndex);
+
+        var canceled = false;
+        var customEscapeCount = 0;
+
+        var editor = new PromptEditor()
+            .EscapeBehavior(PromptEditorEscapeBehavior.CancelCompletionOnly)
+            .CompletionPresentation(PromptEditorCompletionPresentation.InlineCycle)
+            .CompletionHandler(Complete)
+            .Canceled((_, _) => canceled = true)
+            .AutoFocus(true);
+
+        editor.AddCommand(new Command
+        {
+            Id = "Custom.Close",
+            LabelMarkup = "Close",
+            Gesture = new KeyGesture(TerminalKey.Escape),
+            Execute = _ => customEscapeCount++,
+        });
+
+        var root = new VStack { editor };
+
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(40, 6));
+        driver.Tick();
+
+        driver.Backend.PushEvent(new TerminalTextEvent { Text = "h" });
+        driver.TickUntil(() => editor.Text == "h");
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Escape });
+        driver.TickUntil(() => customEscapeCount == 1);
+
+        Assert.IsFalse(canceled);
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Tab });
+        driver.TickUntil(() => editor.Text == "hello");
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Escape });
+        driver.Tick();
+
+        Assert.AreEqual(1, customEscapeCount);
+        Assert.IsFalse(canceled);
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Tab });
+        driver.Tick();
+
+        Assert.AreEqual("hello", editor.Text);
+    }
+
     [TestMethod]
     public void PromptEditor_Uses_Default_Command_Config_When_Config_Is_Null()
     {

src/XenoAtom.Terminal.UI.Tests/UiCommandShortcutTests.cs

@@ -102,6 +102,38 @@ public void CommandSequence_Throws_When_Prefix_Conflicts_With_Standalone_Command
         });
     }
 
+    [TestMethod]
+    public void Disabled_Command_Consumes_Gesture_By_Default()
+    {
+        var probe = new FallbackGestureProbe(allowFallthrough: false);
+        var root = new VStack { probe };
+
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(40, 10));
+        driver.Tick();
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Escape });
+        driver.Tick();
+
+        Assert.AreEqual(0, probe.PrimaryCount);
+        Assert.AreEqual(0, probe.FallbackCount);
+    }
+
+    [TestMethod]
+    public void Disabled_Command_Can_Allow_Gesture_Fallthrough()
+    {
+        var probe = new FallbackGestureProbe(allowFallthrough: true);
+        var root = new VStack { probe };
+
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(40, 10));
+        driver.Tick();
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Escape });
+        driver.Tick();
+
+        Assert.AreEqual(0, probe.PrimaryCount);
+        Assert.AreEqual(1, probe.FallbackCount);
+    }
+
     private sealed class EmptyProbe : Visual
     {
         protected override SizeHints MeasureCore(in LayoutConstraints constraints) => SizeHints.Fixed(constraints.Clamp(new Size(1, 1)));
@@ -137,4 +169,41 @@ protected override void RenderOverride(CellBuffer buffer)
             buffer.WriteText(Bounds.X, Bounds.Y, $"Count:{Count}".AsSpan(), Style.None);
         }
     }
+
+    private sealed class FallbackGestureProbe : Visual
+    {
+        public int PrimaryCount { get; private set; }
+
+        public int FallbackCount { get; private set; }
+
+        public FallbackGestureProbe(bool allowFallthrough)
+        {
+            Focusable = true;
+
+            AddCommand(new Command
+            {
+                Id = "primary",
+                LabelMarkup = "Primary",
+                Gesture = new XenoAtom.Terminal.UI.Input.KeyGesture(TerminalKey.Escape),
+                CanExecute = _ => false,
+                ConsumesGestureWhenUnavailable = allowFallthrough ? false : true,
+                Execute = _ => PrimaryCount++,
+            });
+
+            AddCommand(new Command
+            {
+                Id = "fallback",
+                LabelMarkup = "Fallback",
+                Gesture = new XenoAtom.Terminal.UI.Input.KeyGesture(TerminalKey.Escape),
+                Execute = _ => FallbackCount++,
+            });
+        }
+
+        protected override SizeHints MeasureCore(in LayoutConstraints constraints) => SizeHints.Fixed(constraints.Clamp(new Size(10, 1)));
+
+        protected override void RenderOverride(CellBuffer buffer)
+        {
+            buffer.WriteText(Bounds.X, Bounds.Y, $"P:{PrimaryCount} F:{FallbackCount}".AsSpan(), Style.None);
+        }
+    }
 }

src/XenoAtom.Terminal.UI/Commands/Command.cs

@@ -88,6 +88,14 @@ public sealed class Command
     /// </summary>
     public Func<Visual, bool>? IsVisible { get; init; }
 
+    /// <summary>
+    /// Gets a value indicating whether a matching gesture is treated as handled when the command is hidden or cannot execute.
+    /// </summary>
+    /// <remarks>
+    /// When set to <see langword="false"/>, gesture routing continues to the next matching command instead of consuming the key.
+    /// </remarks>
+    public bool ConsumesGestureWhenUnavailable { get; init; } = true;
+
     /// <summary>
     /// Returns <see langword="true"/> if the command is visible for the specified <paramref name="target"/>.
     /// </summary>

src/XenoAtom.Terminal.UI/Controls/PromptEditor.cs

@@ -34,6 +34,22 @@ public enum PromptEditorEnterMode
     EnterInsertsNewLine = 1,
 }
 
+/// <summary>
+/// Specifies how <see cref="TerminalKey.Escape"/> is interpreted by <see cref="PromptEditor"/>.
+/// </summary>
+public enum PromptEditorEscapeBehavior
+{
+    /// <summary>
+    /// Escape cancels completion when active; otherwise it raises <see cref="PromptEditor.CanceledEvent"/>.
+    /// </summary>
+    CancelPromptOrCompletion = 0,
+
+    /// <summary>
+    /// Escape cancels completion when active and otherwise falls through to other bindings.
+    /// </summary>
+    CancelCompletionOnly = 1,
+}
+
 /// <summary>
 /// Specifies the completion UI mode used by <see cref="PromptEditor"/>.
 /// </summary>
@@ -314,6 +330,9 @@ private static Command CreateCancelCommand(PromptEditorCommandConfig config)
             Gesture = config.Gesture,
             Importance = CommandImportance.Secondary,
             Presentation = CommandPresentation.CommandBar,
+            IsVisible = static v => ((PromptEditor)v).IsCancelCommandVisible,
+            CanExecute = static v => ((PromptEditor)v).CanExecuteCancelCommand,
+            ConsumesGestureWhenUnavailable = false,
             Execute = static v => ((PromptEditor)v).Cancel(),
         };
     }
@@ -430,6 +449,12 @@ private static Command CreateHistoryNextCommand(PromptEditorCommandConfig config
     [Bindable]
     public partial PromptEditorEnterMode EnterMode { get; set; }
 
+    /// <summary>
+    /// Gets or sets how <see cref="TerminalKey.Escape"/> is interpreted.
+    /// </summary>
+    [Bindable]
+    public partial PromptEditorEscapeBehavior EscapeBehavior { get; set; }
+
     /// <summary>
     /// Gets or sets a value indicating whether ghost completion is rendered when available.
     /// </summary>
@@ -515,6 +540,12 @@ protected virtual void OnCanceled(PromptEditorCanceledEventArgs e) { }
     /// <inheritdoc />
     protected override bool ShowPlaceholderWhenUnfocusedOnly => false;
 
+    private bool HasActiveCompletion => _completionActive || _completionPopup is not null;
+
+    private bool CanExecuteCancelCommand => EscapeBehavior == PromptEditorEscapeBehavior.CancelPromptOrCompletion || HasActiveCompletion;
+
+    private bool IsCancelCommandVisible => EscapeBehavior == PromptEditorEscapeBehavior.CancelPromptOrCompletion || HasActiveCompletion;
+
     /// <summary>
     /// Accepts the current text and raises <see cref="AcceptedEvent"/>.
     /// </summary>
@@ -556,7 +587,8 @@ public void InsertNewLine()
     /// <inheritdoc />
     protected override void OnKeyDown(KeyEventArgs e)
     {
-        if (_completionActive && e.Key != TerminalKey.Tab)
+        var hadActiveCompletion = HasActiveCompletion;
+        if (hadActiveCompletion && e.Key != TerminalKey.Tab)
         {
             CancelCompletion();
         }
@@ -575,9 +607,18 @@ protected override void OnKeyDown(KeyEventArgs e)
 
         if (e.Key == TerminalKey.Escape)
         {
-            Cancel();
-            e.Handled = true;
-            return;
+            if (hadActiveCompletion)
+            {
+                e.Handled = true;
+                return;
+            }
+
+            if (EscapeBehavior == PromptEditorEscapeBehavior.CancelPromptOrCompletion)
+            {
+                Cancel();
+                e.Handled = true;
+                return;
+            }
         }
 
         base.OnKeyDown(e);

src/XenoAtom.Terminal.UI/TerminalApp.cs

@@ -2069,7 +2069,12 @@ private bool TryExecuteGestureCommand(TerminalKeyEvent keyEvent, bool allowGloba
 
                 if (!cmd.IsVisibleFor(v) || !cmd.CanExecuteFor(v))
                 {
-                    return true; // gesture matched but is disabled/hidden in this context; treat as handled.
+                    if (cmd.ConsumesGestureWhenUnavailable)
+                    {
+                        return true; // gesture matched but is disabled/hidden in this context; treat as handled.
+                    }
+
+                    continue;
                 }
 
                 cmd.Execute(v);
@@ -2101,7 +2106,12 @@ private bool TryExecuteGestureCommand(TerminalKeyEvent keyEvent, bool allowGloba
 
                 if (!cmd.IsVisibleFor(globalTarget) || !cmd.CanExecuteFor(globalTarget))
                 {
-                    return true;
+                    if (cmd.ConsumesGestureWhenUnavailable)
+                    {
+                        return true;
+                    }
+
+                    continue;
                 }
 
                 cmd.Execute(globalTarget);