1. Home
  2. Docs
  3. Specs & Design Notes
  4. Control Specs
  5. CommandBar

CommandBar Specs

This document specifies the CommandBar control.

This file intentionally focuses on implementation-specific notes for CommandBar and avoids duplicating the broader command specs.

Goals

  • 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.

Non-goals

  • Acting as a command palette or menu (use CommandPalette / MenuBar instead).
  • Handling input directly (it renders hints; the command router executes shortcuts).

Implementation map

  • Control: src/XenoAtom.Terminal.UI/Controls/CommandBar.cs
  • Style: src/XenoAtom.Terminal.UI/Styling/CommandBarStyle.cs
  • Tests: src/XenoAtom.Terminal.UI.Tests/CommandBarRenderingTests.cs
  • Demo: samples/ControlsDemo/Demos/CommandBarDemo.cs

Layout & rendering (current behavior)

  • 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

  • The bar collects local commands from the focused visual chain and global commands from TerminalApp.
  • Commands are filtered by:
    • Presentation flags (default is CommandPresentation.CommandBar)
    • enabled/visible state (Command.IsVisibleFor(target), Command.CanExecuteFor(target))
    • de-duplication by Command.Id (local wins over global).
  • When a command sequence prefix is active, the bar can restrict displayed sequence commands to those matching the prefix.

Styling

  • CommandBarStyle controls:
    • bar background/foreground
    • keycap glyphs and styles
    • label style and disabled label style
    • 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.
  • Optional grouping (local vs global) or ordering by importance/category.