Add bindable query state to command palette

Author: xoofx

samples/ControlsDemo/Demos/CommandPaletteDemo.cs

@@ -24,6 +24,8 @@ public override Visual Build(DemoContext context)
         var verticalAlignment = new State<Align>(Align.Start);
         var offsetX = new State<int>(0);
         var offsetY = new State<int>(0);
+        var clearQueryOnShow = new State<bool>(true);
+        var queryText = new State<string?>(string.Empty);
         var palette = new CommandPalette().Style(() => CommandPaletteStyle.Default with
         {
             PopupWidthPercent = Math.Clamp(widthPercent.Value, 1, 100),
@@ -33,7 +35,9 @@ public override Visual Build(DemoContext context)
             PopupVerticalAlignment = verticalAlignment.Value,
             PopupOffsetX = offsetX.Value,
             PopupOffsetY = offsetY.Value,
-        });
+        })
+            .QueryText(queryText)
+            .ClearQueryOnShow(clearQueryOnShow);
 
         void ShowPalette()
         {
@@ -44,6 +48,14 @@ void ShowPalette()
             DemoUi.Title("Command palette"),
                 new TextBlock("Press Ctrl+P to open the command palette. Type to search, press Enter to run the top match, use arrows to navigate, or resize the window with the mouse.")
                 .Wrap(true),
+                new Group("Query state").Content(new VStack(
+                        new CheckBox("Clear query on show").IsChecked(clearQueryOnShow),
+                        new HStack(
+                                new Button("Preset query").Click(() => queryText.Value = "reset"),
+                                new Button("Clear query").Click(() => queryText.Value = string.Empty))
+                            .Spacing(1),
+                        new TextBlock(() => $"Current query: {queryText.Value}"))
+                    .Spacing(1)),
                 new Group("Popup host style").Content(new VStack(
                         new HStack(
                                 "Width (%):",

site/docs/controls/commandpalette.md

@@ -47,6 +47,7 @@ root.AddCommand(new Command
 When open:
 
 - Type to search
+- `Show()` clears the previous search by default
 - Press Enter to execute the currently highlighted result (the first match by default)
 - Use Up/Down to navigate results
 - Press Down from the search box to move directly to the next result
@@ -79,9 +80,22 @@ palette.Style(CommandPaletteStyle.Default with
 
 `PopupWidthPercent` and `PopupHeightPercent` are optional viewport-relative sizing hints. Alignment (`Start`, `Center`, `End`, `Stretch`) and `PopupOffsetX` / `PopupOffsetY` still control where the popup appears after that size is resolved.
 
+## Query state
+
+`QueryText` is a bindable property on `CommandPalette`, so applications can observe, prefill, or two-way bind the current search text. `ClearQueryOnShow` controls whether `Show()` resets that query before the palette takes focus. It defaults to `true`.
+
+```csharp
+var palette = new CommandPalette
+{
+    ClearQueryOnShow = false,
+    QueryText = "reset",
+};
+```
+
 ## Defaults
 
 - Default popup alignment: `PopupHorizontalAlignment = Align.Center`, `PopupVerticalAlignment = Align.Start`
+- Default query behavior: `ClearQueryOnShow = true`
 
 ## Related
 - [Commands](../commands.md)

site/docs/specs/controls/commandpalette.md

@@ -215,6 +215,11 @@ Introduce `CommandPaletteStyle` (or update existing one) with:
 - optional `DescriptionVisible` / `ShowDescription`
 - optional `MaxWidth`, `ResultsHeight`, padding, etc.
 
+The palette control itself also exposes bindable query state so apps can integrate it with the rest of their UI:
+
+- `QueryText` for the current search text
+- `ClearQueryOnShow` to control whether `Show()` starts from an empty query or preserves the existing one
+
 ### Default item template
 
 Default row visual (single line):

site/img/controls/commandpalette.svg

@@ -112,6 +112,163 @@ public void CommandPalette_Invokes_Action_On_Enter_From_Search()
         driver.TickUntil(() => invoked);
     }
 
+    [TestMethod]
+    public void CommandPalette_QueryText_Tracks_Search_Box_Input()
+    {
+        var root = new VStack();
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(60, 12));
+        driver.Tick();
+
+        var palette = new CommandPalette();
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = "cmd.open",
+            LabelMarkup = "Open",
+            Presentation = CommandPresentation.CommandPalette,
+            Execute = _ => { },
+        });
+
+        palette.Show();
+        driver.Tick();
+
+        driver.Backend.PushEvent(new TerminalTextEvent { Text = "op" });
+        driver.Tick();
+
+        Assert.AreEqual("op", palette.QueryText, "Expected typing in the search box to update the bindable QueryText property.");
+    }
+
+    [TestMethod]
+    public void CommandPalette_Show_Clears_Query_By_Default()
+    {
+        var root = new VStack();
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(60, 12));
+        driver.Tick();
+
+        var palette = new CommandPalette
+        {
+            QueryText = "op",
+        };
+
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = "cmd.open",
+            LabelMarkup = "Open",
+            Presentation = CommandPresentation.CommandPalette,
+            Execute = _ => { },
+        });
+
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = "cmd.build",
+            LabelMarkup = "Build",
+            Presentation = CommandPresentation.CommandPalette,
+            Execute = _ => { },
+        });
+
+        palette.Show();
+        driver.Tick();
+
+        Assert.AreEqual(string.Empty, palette.QueryText, "Expected Show() to clear the previous query by default.");
+
+        var outText = driver.Backend.GetOutText();
+        var screen = new AnsiTestScreen(60, 12);
+        screen.Apply(outText);
+        var rendered = screen.GetText();
+
+        StringAssert.Contains(rendered, "Open");
+        StringAssert.Contains(rendered, "Build");
+    }
+
+    [TestMethod]
+    public void CommandPalette_Show_Can_Preserve_Query_When_Configured()
+    {
+        var root = new VStack();
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(60, 12));
+        driver.Tick();
+
+        var palette = new CommandPalette
+        {
+            ClearQueryOnShow = false,
+            QueryText = "op",
+        };
+
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = "cmd.open",
+            LabelMarkup = "Open",
+            Presentation = CommandPresentation.CommandPalette,
+            Execute = _ => { },
+        });
+
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = "cmd.build",
+            LabelMarkup = "Build",
+            Presentation = CommandPresentation.CommandPalette,
+            Execute = _ => { },
+        });
+
+        palette.Show();
+        driver.Tick();
+
+        Assert.AreEqual("op", palette.QueryText, "Expected Show() to preserve the query when ClearQueryOnShow is disabled.");
+
+        var outText = driver.Backend.GetOutText();
+        var screen = new AnsiTestScreen(60, 12);
+        screen.Apply(outText);
+        var rendered = screen.GetText();
+
+        StringAssert.Contains(rendered, "Open");
+        Assert.IsFalse(rendered.Contains("Build", StringComparison.Ordinal), "Expected the preserved query to remain active when the palette opens.");
+    }
+
+    [TestMethod]
+    public void CommandPalette_QueryText_Can_Be_Set_Programmatically_While_Open()
+    {
+        var root = new VStack();
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(60, 12));
+        driver.Tick();
+
+        var palette = new CommandPalette
+        {
+            ClearQueryOnShow = false,
+        };
+
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = "cmd.open",
+            LabelMarkup = "Open",
+            Presentation = CommandPresentation.CommandPalette,
+            Execute = _ => { },
+        });
+
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = "cmd.build",
+            LabelMarkup = "Build",
+            Presentation = CommandPresentation.CommandPalette,
+            Execute = _ => { },
+        });
+
+        palette.Show();
+        driver.Tick();
+
+        palette.QueryText = "build";
+        driver.Tick();
+
+        var searchBox = GetPrivateField<TextBox>(palette, "_searchBox");
+        Assert.AreEqual("build", palette.QueryText);
+        Assert.AreEqual("build", searchBox.Text, "Expected programmatic QueryText updates to synchronize the search box content.");
+
+        var outText = driver.Backend.GetOutText();
+        var screen = new AnsiTestScreen(60, 12);
+        screen.Apply(outText);
+        var rendered = screen.GetText();
+
+        StringAssert.Contains(rendered, "Build");
+        Assert.IsFalse(rendered.Contains("Open", StringComparison.Ordinal), "Expected programmatic QueryText updates to re-filter the palette immediately.");
+    }
+
     [TestMethod]
     public void CommandPalette_Down_From_Search_Advances_To_Second_Item()
     {