CommandPalette

Overview

CommandPalette is built directly on NaviusOverlaySurfaceBase, the same Dialog/AlertDialog/Drawer substrate documented for Dialog: that base class already supplies the modal backdrop, focus trap, Escape and outside-click dismissal, and enter/exit fade, so this control only adds a search input, a filtered and grouped row list, and keyboard-driven execution on top of it. Filtering and highlight movement are pure functions in CommandPaletteEngine, which itself consumes Navius.Wpf.Primitives’ AutocompleteEngine rather than duplicating its filter/highlight-move math, using the same never-move-real-focus model as NaviusAutocompleteBase.

Usage

xmlns:navius="clr-namespace:Navius.Wpf.Primitives.Controls;assembly=Navius.Wpf.Primitives"
xmlns:overlay="clr-namespace:Navius.Wpf.Primitives.Controls.OverlaySurface;assembly=Navius.Wpf.Primitives"
xmlns:commandPalette="clr-namespace:Navius.Wpf.Ui.CommandPalette;assembly=Navius.Wpf.Ui"

<Grid>
    <!-- app content -->
    <navius:NaviusButton Content="Open command palette (Ctrl+K)" Click="OnOpenPaletteClick" />

    <!-- one layer per window, stretched over the root -->
    <overlay:NaviusOverlayLayer>
        <commandPalette:NaviusCommandPalette
            x:Name="CommandPalette"
            Title="Command palette"
            Placeholder="Type a command or search..." />
    </overlay:NaviusOverlayLayer>
</Grid>

Items is populated from code-behind (or a binding), each entry a CommandPaletteItem carrying a label, an optional group, and an ICommand:

CommandPalette.Items = new[]
{
    new CommandPaletteItem("Go to Dashboard", group: "Navigation", command: goToDashboardCommand),
    new CommandPaletteItem("New File", group: "Actions", command: newFileCommand),
};

Requires a NaviusOverlayLayer in the window, same as Dialog; opening without one logs a Trace.TraceWarning and reverts IsOpen to false.

Properties

Property	Type	Default	From	Description
Items	IReadOnlyList<CommandPaletteItem>	empty array	NaviusCommandPalette	The full command set. Adjacent items sharing a Group are pre-clustered so a header renders once per group.
Query	string	""	NaviusCommandPalette	Two-way bindable search text; also bound directly from the template’s PART_Input textbox.
Placeholder	string?	"Type a command..."	NaviusCommandPalette	Shown in the input while Query is empty.
HighlightedIndex	int	-1	NaviusCommandPalette	Index into FilteredRows of the virtually-highlighted row (never real keyboard focus).
FilteredRows	ObservableCollection<CommandPaletteRow>	-	NaviusCommandPalette	Read-only. The rows the template’s PART_List binds to: each filtered Items entry plus its flat index and whether a group header renders above it.
IsEmpty	bool	true	NaviusCommandPalette	Read-only. True when FilteredRows is empty; drives the template’s “No matching commands” text.
IsOpen	bool	false	NaviusOverlaySurfaceBase	Open state. Two-way bindable by default.
Title	string?	null	NaviusOverlaySurfaceBase	Accessible name, applied via AutomationProperties.Name on engage.
Description	string?	null	NaviusOverlaySurfaceBase	Accessible help text, applied via AutomationProperties.HelpText on engage.

Methods

Method	Description
Open()	Inherited from NaviusOverlaySurfaceBase. Sets IsOpen to true via SetCurrentValue, preserving an existing two-way binding.
Close()	Inherited from NaviusOverlaySurfaceBase. Sets IsOpen to false via SetCurrentValue, preserving an existing two-way binding. Also called after Enter runs the highlighted item.

Events

Event	Signature	Fires when
Opened	EventHandler	Inherited from NaviusOverlaySurfaceBase. The overlay has engaged and its enter animation started.
Closing	EventHandler<OverlayClosingEventArgs>	Inherited from NaviusOverlaySurfaceBase. A close was requested (Escape, outside press, IsOpen = false, or Enter execution). Cancelable.
Closed	EventHandler	Inherited from NaviusOverlaySurfaceBase. The exit animation completed and the surface left its layer.

Keyboard interactions

Key	Behavior
ArrowDown	Moves HighlightedIndex forward one row via CommandPaletteEngine.MoveHighlight; stops at the last row (no wrap).
ArrowUp	Moves HighlightedIndex back one row; stops at the first row (no wrap).
Home	Jumps to the first row, when any rows are present.
End	Jumps to the last row, when any rows are present.
Enter	Runs the highlighted item’s ICommand (if executable) via CommandPaletteEngine.Execute, then closes the palette.
Escape	Closes the palette, routed through the shared OverlayStack PreviewKeyDown hook inherited from NaviusOverlaySurfaceBase; fixed on, not configurable.

UIA mechanism

NaviusCommandPaletteAutomationPeer (a FrameworkElementAutomationPeer) overrides GetAutomationControlTypeCore() to return AutomationControlType.Window and IsDialogCore() to return true, the same mapping Dialog/AlertDialog/Drawer use. Title and Description are applied as AutomationProperties.Name and AutomationProperties.HelpText on engage by the inherited NaviusOverlaySurfaceBase.Engage() logic. The M6 audit confirmed the template’s PART_Input and PART_List x:Names both exist and that the C# lookup (GetTemplateChild(PartInput)) matches; PART_List is declared for designers but never retrieved in code. No animation is owned by this control itself, the enter/exit fade is inherited from NaviusOverlaySurfaceBase. The unit suite exercises CommandPaletteEngine’s filter/highlight-move/execute logic directly, plus that a new NaviusCommandPalette starts closed and that setting IsOpen with no host NaviusOverlayLayer reverts to false.