Add multi-line wrapping mode to CommandBar

xoofx · xoofx · commit bffca77c2863 · 2026-04-06T00:31:48.000+02:00
diff --git a/samples/ControlsDemo/Demos/CommandBarDemo.cs b/samples/ControlsDemo/Demos/CommandBarDemo.cs
@@ -2,6 +2,7 @@
 using XenoAtom.Terminal.UI;
 using XenoAtom.Terminal.UI.Commands;
 using XenoAtom.Terminal.UI.Controls;
+using XenoAtom.Terminal.UI.Geometry;
 using XenoAtom.Terminal.UI.Input;
 
 namespace XenoAtom.Terminal.UI.ControlsDemo.Demos;
@@ -19,20 +20,26 @@ public override Visual Build(DemoContext context)
 
         var counter = new State<int>(0);
         var enabled = new State<bool>(true);
+        var multiLine = new State<bool>(false);
 
         var editor = new TextBox().Placeholder("Focus me to populate the command bar…");
         editor.AutoFocus(true);
+        var commandBar = new CommandBar()
+            .MultiLine(() => multiLine.Value)
+            .MaxWidth(34);
 
         var root = new VStack(
                 DemoUi.Hint("CommandBar surfaces commands registered on the focused visual (and its parents), plus app-level commands."),
                 editor,
                 new HStack(
                         new Button("Increment").Click(() => counter.Value++),
-                        new CheckBox("Enabled").IsChecked(enabled))
+                        new CheckBox("Enabled").IsChecked(enabled),
+                        new CheckBox("Multi-line bar").IsChecked(multiLine))
                     .Spacing(2),
                 new TextBlock(() => $"Counter: {counter.Value}"),
+                DemoUi.Hint("The command bar below is width-limited to make clipping vs wrapping easy to compare."),
                 new Rule(),
-                new CommandBar())
+                new Border(commandBar).Padding(new Thickness(1, 0, 1, 0)))
             .Spacing(1);
 
         root.AddCommand(new Command
@@ -56,7 +63,26 @@ public override Visual Build(DemoContext context)
             Execute = _ => counter.Value = 0,
         });
 
+        root.AddCommand(new Command
+        {
+            Id = "Demo.Randomize",
+            LabelMarkup = "Randomize value",
+            Gesture = new KeyGesture(TerminalChar.CtrlD, TerminalModifiers.Ctrl),
+            Importance = CommandImportance.Primary,
+            Presentation = CommandPresentation.CommandBar,
+            Execute = _ => counter.Value = (counter.Value + 7) % 10,
+        });
+
+        root.AddCommand(new Command
+        {
+            Id = "Demo.Export",
+            LabelMarkup = "Export snapshot",
+            Gesture = new KeyGesture(TerminalChar.CtrlS, TerminalModifiers.Ctrl),
+            Importance = CommandImportance.Secondary,
+            Presentation = CommandPresentation.CommandBar,
+            Execute = _ => { },
+        });
+
         return root;
     }
 }
-
diff --git a/site/docs/controls/commandbar.md b/site/docs/controls/commandbar.md
@@ -4,7 +4,7 @@ title: CommandBar
 
 # CommandBar
 
-`CommandBar` displays a single-row “key hints” strip for the current focus context.
+`CommandBar` displays a “key hints” strip for the current focus context.
 
 It collects `Command` instances registered on the focused visual (and its parents) plus app-level commands, then renders
 them as a sequence of keycaps and labels.
@@ -31,9 +31,24 @@ var root = new DockLayout()
 Terminal.Run(root);
 ```
 
+## Multi-line wrapping
+
+By default, `CommandBar` keeps the existing single-row behavior and clips entries that do not fit.
+
+If you want commands to wrap onto additional rows instead, enable `MultiLine`:
+
+```csharp
+var bar = new CommandBar()
+    .MultiLine(true);
+```
+
+In multi-line mode, a command entry is moved to the next row when it does not fit in the remaining space on the current row.
+The default remains `false`.
+
 ## Defaults
 
 - Default alignment: `HorizontalAlignment = Align.Start`, `VerticalAlignment = Align.Start` 
+- `MultiLine = false`
 
 ## Styling
 Use `CommandBarStyle` to change bar/keycap colors:
diff --git a/site/docs/specs/controls/commandbar.md b/site/docs/specs/controls/commandbar.md
@@ -18,7 +18,7 @@ This file intentionally focuses on *implementation-specific* notes for `CommandB
 
 ## Goals
 
-- Provide a lightweight, single-row “key hints” surface intended for app chrome (footer/header).
+- Provide a lightweight “key hints” surface intended for app chrome (footer/header).
 - Surface commands relevant to the current focus context and app/global commands.
 - Stay allocation-conscious and compatible with the binding dirty model.
 
@@ -36,9 +36,14 @@ This file intentionally focuses on *implementation-specific* notes for `CommandB
 
 ## Layout & rendering (current behavior)
 
-- The control measures to a single row (`Height = 1`) and to the *current* content width (focused context), while allowing clipping when the available width is smaller.
-- Render always clears the entire bar row using `CommandBarStyle.Resolve(theme).BarStyle` (chrome must not “inherit” background/attributes from content behind it).
-- When a key sequence prefix is active (`TerminalApp.PendingCommandSequenceCount > 0`), `CommandBar` renders the pending prefix + `…` before regular entries.
+- `MultiLine = false` is the default and preserves the existing single-row behavior:
+  - the control measures to a single row (`Height = 1`) and to the *current* content width (focused context), while allowing clipping when the available width is smaller
+  - render clears the entire bar row using `CommandBarStyle.Resolve(theme).BarStyle` (chrome must not “inherit” background/attributes from content behind it)
+- `MultiLine = true` allows wrapped layout:
+  - the control may measure to multiple rows when the available width is bounded
+  - command entries wrap as atomic units; if an entry does not fit in the remaining space on the current row, it starts on the next row
+  - separators are not rendered at the start of a wrapped row
+- In both modes, when a key sequence prefix is active (`TerminalApp.PendingCommandSequenceCount > 0`), `CommandBar` renders the pending prefix + `…` before regular entries.
 
 ## Command collection
 
@@ -58,6 +63,11 @@ This file intentionally focuses on *implementation-specific* notes for `CommandB
   - separator text
 - Labels are rendered from `Command.LabelMarkup` via `MarkupTextParser` using the current theme markup styles.
 
+## Public API
+
+- `Presentation : CommandPresentation`
+- `MultiLine : bool` (default `false`)
+
 ## Future ideas
 
 - Optional “More…” entry that opens a help/palette surface when there is insufficient space.
diff --git a/src/XenoAtom.Terminal.UI.Tests/CommandBarRenderingTests.cs b/src/XenoAtom.Terminal.UI.Tests/CommandBarRenderingTests.cs
@@ -2,6 +2,7 @@
 // Licensed under the BSD-Clause 2 license.
 // See license.txt file in the project root for full license information.
 
+using System.Linq;
 using XenoAtom.Terminal.UI.Commands;
 using XenoAtom.Terminal.UI.Controls;
 using XenoAtom.Terminal.UI.Hosting;
@@ -39,6 +40,68 @@ public void CommandBar_Renders_Local_And_Global_Commands()
         StringAssert.Contains(outText, "Probe");
     }
 
+    [TestMethod]
+    public void CommandBar_Default_Mode_Remains_Single_Row_When_Commands_Do_Not_Fit()
+    {
+        var probe = new WrappingProbe();
+        var bar = new CommandBar();
+        var layout = new DockLayout { Content = probe, Bottom = bar };
+
+        using var driver = new TerminalAppTestDriver(layout, TerminalHostKind.Fullscreen, new TerminalSize(20, 6));
+        driver.App.Focus(probe);
+        driver.Tick();
+
+        Assert.AreEqual(1, bar.Bounds.Height);
+
+        var lines = GetScreenLines(driver, 20, 6);
+        var renderedCommandRows = lines.Count(static line => line.Contains("Alpha", StringComparison.Ordinal) || line.Contains("Beta", StringComparison.Ordinal) || line.Contains("Gamma", StringComparison.Ordinal));
+        Assert.AreEqual(1, renderedCommandRows);
+    }
+
+    [TestMethod]
+    public void CommandBar_MultiLine_Wraps_Commands_To_Additional_Rows()
+    {
+        var probe = new WrappingProbe();
+        var bar = new CommandBar().MultiLine(true);
+        var layout = new DockLayout { Content = probe, Bottom = bar };
+
+        using var driver = new TerminalAppTestDriver(layout, TerminalHostKind.Fullscreen, new TerminalSize(20, 6));
+        driver.App.Focus(probe);
+        driver.Tick();
+
+        Assert.IsTrue(bar.Bounds.Height > 1, $"Expected wrapped command bar to request multiple rows, actual height={bar.Bounds.Height}.");
+
+        var lines = GetScreenLines(driver, 20, 6);
+        var alphaRow = FindLine(lines, "Alpha");
+        var betaRow = FindLine(lines, "Beta");
+        var gammaRow = FindLine(lines, "Gamma");
+
+        Assert.IsTrue(alphaRow >= 0, "Expected Alpha to render.");
+        Assert.IsTrue(betaRow >= 0, "Expected Beta to render.");
+        Assert.IsTrue(gammaRow >= 0, "Expected Gamma to render.");
+        Assert.IsTrue(alphaRow != betaRow || betaRow != gammaRow, "Expected wrapped commands to span multiple rows.");
+    }
+
+    private static string[] GetScreenLines(TerminalAppTestDriver driver, int width, int height)
+    {
+        var screen = new AnsiTestScreen(width, height);
+        screen.Apply(driver.Backend.GetOutText());
+        return screen.GetText().Split('\n');
+    }
+
+    private static int FindLine(string[] lines, string text)
+    {
+        for (var i = 0; i < lines.Length; i++)
+        {
+            if (lines[i].Contains(text, StringComparison.Ordinal))
+            {
+                return i;
+            }
+        }
+
+        return -1;
+    }
+
     private sealed class CommandProbe : Visual
     {
         public CommandProbe()
@@ -61,4 +124,39 @@ protected override void RenderOverride(Rendering.CellBuffer buffer)
         {
         }
     }
+
+    private sealed class WrappingProbe : Visual
+    {
+        public WrappingProbe()
+        {
+            Focusable = true;
+            AddCommand(new Command
+            {
+                Id = "alpha",
+                LabelMarkup = "Alpha",
+                Gesture = new KeyGesture(TerminalChar.CtrlA, TerminalModifiers.Ctrl),
+                Execute = _ => { },
+            });
+            AddCommand(new Command
+            {
+                Id = "beta",
+                LabelMarkup = "Beta",
+                Gesture = new KeyGesture(TerminalChar.CtrlB, TerminalModifiers.Ctrl),
+                Execute = _ => { },
+            });
+            AddCommand(new Command
+            {
+                Id = "gamma",
+                LabelMarkup = "Gamma",
+                Gesture = new KeyGesture(TerminalChar.CtrlG, TerminalModifiers.Ctrl),
+                Execute = _ => { },
+            });
+        }
+
+        protected override SizeHints MeasureCore(in LayoutConstraints constraints) => SizeHints.Fixed(constraints.Clamp(new Geometry.Size(10, 1)));
+
+        protected override void RenderOverride(Rendering.CellBuffer buffer)
+        {
+        }
+    }
 }
diff --git a/src/XenoAtom.Terminal.UI/Controls/CommandBar.cs b/src/XenoAtom.Terminal.UI/Controls/CommandBar.cs
