Tesserae - Command Palette

CommandPalette

Description

A command palette utility

CommandPalette provides a fast and efficient way for users to navigate an application and trigger commands using only their keyboard. Inspired by modern editors and tools, it allows users to search through a list of actions and execute them with a single keystroke.

The search field is a real OmniBox in Search mode rather than a bare input, so a palette can offer the snaps, value filters, history and suggestions the app's own search box offers. Reach it with .SearchBox, or configure it with .ConfigureSearchBox(...). OnSearch hands over the parsed OmniBox.SearchQuery — the string overload is still there — and adding or removing a chip re-runs the search the way typing does.

Clicking beside the palette closes it, the way it does on a Modal: CanLightDismiss (on by default), LightDismiss() and NoLightDismiss() control that. Escape closes the palette wherever focus ended up after a row was activated.

Sample

command-palette-sample.cs

using System.Collections.Generic;
using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static IEnumerable<CommandPaletteAction> BuildActions()
        {
            var navigate = new CommandPaletteAction("navigation", "Navigate");
            var home = new CommandPaletteAction("home", "Go to Home")
            {
                ParentId = "navigation",
                Perform = () => Toast().Success("Home"),
            };
            var settings = new CommandPaletteAction("settings", "Open Settings")
            {
                ParentId = "navigation",
                Perform = () => Toast().Success("Settings"),
            };
            var help = new CommandPaletteAction("help", "Help Center")
            {
                Perform = () => Toast().Success("Help"),
                Shortcut = new[] { "?" },
                Keywords = "support docs",
                Icon = UIcons.CommentsQuestion,
            };
            var create = new CommandPaletteAction("new", "Create Item")
            {
                Perform = () => Toast().Success("Create"),
                Shortcut = new[] { "n" },
                Section = "Actions",
                Icon = UIcons.Plus,
            };
            var archive = new CommandPaletteAction("archive", "Archive Item")
            {
                Perform = () => Toast().Success("Archive"),
                Section = "Actions",
                Icon = UIcons.Archive,
            };

            return new[]
            {
                navigate,
                home,
                settings,
                help,
                create,
                archive,
            };
        }

        private static void Main()
        {
            CommandPalette palette = null;

            var component = VStack().Children(
                TextBlock("Use the button below or press Cmd/Ctrl + K to open the palette.").Small().Secondary().PB(8),
                Button("Open Command Palette").Primary().OnClick(() => palette.Open()),
                TextBlock("Try navigating with arrow keys, Enter, Esc, and Backspace for nested items.").Small().Secondary().PT(12)
            );

            palette = new CommandPalette(component, BuildActions());

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component);
        }
    }
}

API reference

class

CommandPalette

public sealed class CommandPalette : Layer<CommandPalette>

A keyboard-driven full-screen command launcher (Ctrl/Cmd-K style) that lets users search and invoke application commands.

Namespace: Tesserae
Inheritance: Layer<CommandPalette> → CommandPalette

Constructors

Name	Description
CommandPalette	Creates a CommandPalette whose global Ctrl/Cmd keyboard listener is bound to the lifetime of `host`: the listener is attached when `host` first mounts to the DOM and detached when it is removed. This prevents the palette from leaking listeners (and continuing to respond to its shortcut) after the owning view has been navigated away.

Constructor

CommandPalette

public CommandPalette(IComponent host, IEnumerable<CommandPaletteAction> actions = null)

Creates a CommandPalette whose global Ctrl/Cmd keyboard listener is bound to the lifetime of host: the listener is attached when host first mounts to the DOM and detached when it is removed. This prevents the palette from leaking listeners (and continuing to respond to its shortcut) after the owning view has been navigated away.

Properties

Name	Description
EnableGlobalShortcut	Enables the global shortcut on the component.
EnableGlobalActionShortcuts	Enables the global action shortcuts on the component.
HideOnAction	Hides the on action.
GlobalShortcutKey	Key (combined with Ctrl/Cmd) that toggles the palette globally. Case-insensitive. Defaults to "k".
CanLightDismiss	Whether clicking beside the palette closes it, the way it does on a `Modal`. On by default.
SearchBox	The box the palette is typed into. It is a full `OmniBox`, so a host can give the palette the same snaps, value filters, history and suggestions its own search box has instead of the palette being a lesser search than the page it stands in for.
Placeholder	Gets or sets the placeholder text shown when the component is empty.
EmptyText	What is said when there is nothing to show. Defaults to "No results", which is right for a palette that filters a list it already has; a palette that goes and searches usually wants to say what to do instead ("Type to search").
CurrentQuery	What is typed in the palette's search box right now, trimmed.

Property

CommandPalette.EnableGlobalShortcut

public bool EnableGlobalShortcut { get; set; }

Enables the global shortcut on the component.

Property

CommandPalette.EnableGlobalActionShortcuts

public bool EnableGlobalActionShortcuts { get; set; }

Enables the global action shortcuts on the component.

Property

CommandPalette.HideOnAction

public bool HideOnAction { get; set; }

Hides the on action.

Property

CommandPalette.GlobalShortcutKey

public string GlobalShortcutKey { get; set; }

Key (combined with Ctrl/Cmd) that toggles the palette globally. Case-insensitive. Defaults to "k".

Property

CommandPalette.CanLightDismiss

public bool CanLightDismiss { get ; set ; }

Whether clicking beside the palette closes it, the way it does on a Modal. On by default.

Property

CommandPalette.SearchBox

public OmniBox SearchBox

The box the palette is typed into. It is a full OmniBox, so a host can give the palette the same snaps, value filters, history and suggestions its own search box has instead of the palette being a lesser search than the page it stands in for.

Property

CommandPalette.Placeholder

public string Placeholder { get ; set ; }

Gets or sets the placeholder text shown when the component is empty.

Property

CommandPalette.EmptyText

public string EmptyText { get ; set ; }

What is said when there is nothing to show. Defaults to "No results", which is right for a palette that filters a list it already has; a palette that goes and searches usually wants to say what to do instead ("Type to search").

Property

CommandPalette.CurrentQuery

public string CurrentQuery

What is typed in the palette's search box right now, trimmed.

Methods

Name	Description
LightDismiss	Enables light-dismiss behaviour (clicking outside the palette closes it).
NoLightDismiss	Removes / disables the light dismiss on the component.
ConfigureSearchBox	Configures `SearchBox` - the place to hand the palette the search box configuration the rest of the app shares.
SetActions	Sets the actions of the component.
AddAction	Adds the given action to the component.
SetResults	Puts rows of the host's own at the top of the palette, above its actions - search results drawn as `OmniResult{T}`s, recent files, anything a list of actions can't say. Each carries what Enter does with it, and they take part in the arrow-key walk like any other row. These are shown as given: the palette does not filter them, because the host that produced them for a query already knows which ones answer it. Use `OnSearch` to have them refreshed as the query changes, or call this whenever the host has new ones.
OnSearch	Asks the host for the rows to show, every time the query changes and once when the palette opens. The call is debounced, and an answer that arrives after a newer query was typed is dropped, so a slow search can never overwrite a faster one behind it.
Open	Opens the component.
Close	Closes the component.
Toggle	Toggles the component's state.
Show	Shows the component.
Hide	Hides the component.

Method

CommandPalette.LightDismiss

public CommandPalette LightDismiss()

Enables light-dismiss behaviour (clicking outside the palette closes it).

Method

CommandPalette.NoLightDismiss

public CommandPalette NoLightDismiss()

Removes / disables the light dismiss on the component.

Method

CommandPalette.ConfigureSearchBox

public CommandPalette ConfigureSearchBox(Action<OmniBox> configure)

Configures SearchBox - the place to hand the palette the search box configuration the rest of the app shares.

Method

CommandPalette.SetActions

public CommandPalette SetActions(IEnumerable<CommandPaletteAction> actions)

Sets the actions of the component.

Method

CommandPalette.AddAction

public CommandPalette AddAction(CommandPaletteAction action)

Adds the given action to the component.

Method

CommandPalette.SetResults

Overload

SetResults(IEnumerable<CommandPaletteResult>) Puts rows of the host's own at the top of the palette, above its actions - search results drawn as OmniResult{T}s, recent files, anything a list of actions can't say. Each carries what Enter does with it, and they take part in the arrow-key walk like any other row. These are shown as given: the palette does not filter them, because the host that produced them for a query already knows which ones answer it. Use OnSearch to have them refreshed as the query changes, or call this whenever the host has new ones.

SetResults(CommandPaletteResult[]) Puts one row of the host's own at the top of the palette. See SetResults.

Overload
SetResults(IEnumerable<CommandPaletteResult>)	Puts rows of the host's own at the top of the palette, above its actions - search results drawn as `OmniResult{T}`s, recent files, anything a list of actions can't say. Each carries what Enter does with it, and they take part in the arrow-key walk like any other row. These are shown as given: the palette does not filter them, because the host that produced them for a query already knows which ones answer it. Use `OnSearch` to have them refreshed as the query changes, or call this whenever the host has new ones.
SetResults(CommandPaletteResult[])	Puts one row of the host's own at the top of the palette. See `SetResults`.

SetResults(IEnumerable<CommandPaletteResult>)

public CommandPalette SetResults(IEnumerable<CommandPaletteResult> results)

Puts rows of the host's own at the top of the palette, above its actions - search results drawn as OmniResult{T}s, recent files, anything a list of actions can't say. Each carries what Enter does with it, and they take part in the arrow-key walk like any other row. These are shown as given: the palette does not filter them, because the host that produced them for a query already knows which ones answer it. Use OnSearch to have them refreshed as the query changes, or call this whenever the host has new ones.

Parameters

results IEnumerable<CommandPaletteResult>

SetResults(CommandPaletteResult[])

public CommandPalette SetResults(params CommandPaletteResult[] results)

Puts one row of the host's own at the top of the palette. See SetResults.

Parameters

results CommandPaletteResult[]

Method

CommandPalette.OnSearch

Overload
OnSearch(Func<OmniBox.SearchQuery, Task<IEnumerable<CommandPaletteResult>>>, int)	Asks the host for the rows to show, every time the query changes and once when the palette opens. The call is debounced, and an answer that arrives after a newer query was typed is dropped, so a slow search can never overwrite a faster one behind it.
OnSearch(Func<string, Task<IEnumerable<CommandPaletteResult>>>, int)	Asks the host for the rows to show, for a palette that only needs the text that was typed. See `OnSearch` for the overload that also hands over the box's filters.

OnSearch(Func<OmniBox.SearchQuery, Task<IEnumerable<CommandPaletteResult>>>, int)

public CommandPalette OnSearch(Func<OmniBox.SearchQuery, Task<IEnumerable<CommandPaletteResult>>> search, int debounceMs = 200)

Asks the host for the rows to show, every time the query changes and once when the palette opens. The call is debounced, and an answer that arrives after a newer query was typed is dropped, so a slow search can never overwrite a faster one behind it.

Parameters

search Func<OmniBox.SearchQuery, Task<IEnumerable<CommandPaletteResult>>>: Given what the box says - parsed, with whatever snaps and value filters the host registered on SearchBox already picked out of it - the rows to show. Null clears the search.
debounceMs int: How long typing has to stop before the search runs.

OnSearch(Func<string, Task<IEnumerable<CommandPaletteResult>>>, int)

public CommandPalette OnSearch(Func<string, Task<IEnumerable<CommandPaletteResult>>> search, int debounceMs = 200)

Asks the host for the rows to show, for a palette that only needs the text that was typed. See OnSearch for the overload that also hands over the box's filters.

Parameters

search Func<string, Task<IEnumerable<CommandPaletteResult>>>
debounceMs int

Method

CommandPalette.Open

public CommandPalette Open()

Opens the component.

Method

CommandPalette.Close

public CommandPalette Close()

Closes the component.

Method

CommandPalette.Toggle

public CommandPalette Toggle()

Toggles the component's state.

Method

CommandPalette.Show

public override CommandPalette Show()

Shows the component.

Method

CommandPalette.Hide

public override void Hide(Action onHidden = null)

Hides the component.

Events

Name	Description
ActionExecuted	Raised when action executed occurs.
ResultActivated	Raised when one of the host's own rows is activated - see `SetResults`.

Event

CommandPalette.ActionExecuted

public event Action<CommandPaletteAction> ActionExecuted

Raised when action executed occurs.

Event

CommandPalette.ResultActivated

public event Action<CommandPaletteResult> ResultActivated

Raised when one of the host's own rows is activated - see SetResults.

Fields

Name	Description
LAYER_FADE_OUT_MS	How long `Layer{T}` takes to fade a hidden layer out before removing it.

Field

CommandPalette.LAYER_FADE_OUT_MS

private const int LAYER_FADE_OUT_MS = 150

How long Layer{T} takes to fade a hidden layer out before removing it.

class

CommandPaletteResult

public sealed class CommandPaletteResult

A row of the host's own in a CommandPalette - a search result drawn as an OmniResult{T}, a recent file, a preview card - rather than one of the palette's actions.

Namespace: Tesserae

Constructors

Name	Description
CommandPaletteResult	A row and what Enter does with it. With no `activate` the row is only clickable, which is what a component that already answers its own click (an `OmniResult{T}` with an `OpenWith`) wants.

Constructor

CommandPaletteResult

public CommandPaletteResult(IComponent component, Action activate = null)

A row and what Enter does with it. With no activate the row is only clickable, which is what a component that already answers its own click (an OmniResult{T} with an OpenWith) wants.

Properties

Name	Description
Component	The row itself.
Activate	What Enter - and a click, when it is given - does with the row.
Section	The heading this row sits under, when a palette groups its rows.

Property

CommandPaletteResult.Component

public IComponent Component { get; }

The row itself.

Property

CommandPaletteResult.Activate

public Action Activate { get; }

What Enter - and a click, when it is given - does with the row.

Property

CommandPaletteResult.Section

public string Section { get; set; }

The heading this row sits under, when a palette groups its rows.

class

CommandPaletteAction

public sealed class CommandPaletteAction

Namespace: Tesserae

Constructors

Name	Description
CommandPaletteAction	Initializes a new instance of this class.

Constructor

CommandPaletteAction

public CommandPaletteAction(string id, string name)

Initializes a new instance of this class.

Properties

Name	Description
Id	Sets the DOM id of the component.
Name	Gets or sets the name of the component.
Subtitle	Gets or sets the subtitle.
Keywords	Gets or sets the keywords.
Section	Gets or sets the section.
ParentId	Gets or sets the parent id.
Icon	Gets or sets the icon shown by the component.
Shortcut	Gets or sets the shortcut.
IsEnabled	Gets or sets a value indicating whether the component is interactive (enabled).
IsVisible	Gets a value indicating whether the component is currently visible.
Perform	Gets or sets the perform.

Property

CommandPaletteAction.Id

public string Id { get; }

Sets the DOM id of the component.

Property

CommandPaletteAction.Name

public string Name { get; set; }

Gets or sets the name of the component.

Property

CommandPaletteAction.Subtitle

public string Subtitle { get; set; }

Gets or sets the subtitle.

Property

CommandPaletteAction.Keywords

public string Keywords { get; set; }

Gets or sets the keywords.

Property

CommandPaletteAction.Section

public string Section { get; set; }

Gets or sets the section.

Property

CommandPaletteAction.ParentId

public string ParentId { get; set; }

Gets or sets the parent id.

Property

CommandPaletteAction.Icon

public UIcons? Icon { get; set; }

Gets or sets the icon shown by the component.

Property

CommandPaletteAction.Shortcut

public string[] Shortcut { get; set; }

Gets or sets the shortcut.

Property

CommandPaletteAction.IsEnabled

public bool IsEnabled { get; set; }

Gets or sets a value indicating whether the component is interactive (enabled).

Property

CommandPaletteAction.IsVisible

public bool IsVisible { get; set; }

Gets a value indicating whether the component is currently visible.

Property

CommandPaletteAction.Perform

public Action Perform { get; set; }

Gets or sets the perform.

CommandPalette

Description

Sample

API reference

Constructors

CommandPalette

Properties

CommandPalette.EnableGlobalShortcut

CommandPalette.EnableGlobalActionShortcuts

CommandPalette.HideOnAction

CommandPalette.GlobalShortcutKey

CommandPalette.CanLightDismiss

CommandPalette.SearchBox

CommandPalette.Placeholder

CommandPalette.EmptyText

CommandPalette.CurrentQuery

Methods

CommandPalette.LightDismiss

CommandPalette.NoLightDismiss

CommandPalette.ConfigureSearchBox

CommandPalette.SetActions

CommandPalette.AddAction

CommandPalette.SetResults

SetResults(IEnumerable<CommandPaletteResult>)

Parameters

SetResults(CommandPaletteResult[])

Parameters

CommandPalette.OnSearch

OnSearch(Func<OmniBox.SearchQuery, Task<IEnumerable<CommandPaletteResult>>>, int)

Parameters

OnSearch(Func<string, Task<IEnumerable<CommandPaletteResult>>>, int)

Parameters

CommandPalette.Open

CommandPalette.Close

CommandPalette.Toggle

CommandPalette.Show

CommandPalette.Hide

Events

CommandPalette.ActionExecuted

CommandPalette.ResultActivated

Fields

CommandPalette.LAYER_FADE_OUT_MS

Constructors

CommandPaletteResult

Properties

CommandPaletteResult.Component

CommandPaletteResult.Activate

CommandPaletteResult.Section

Constructors

CommandPaletteAction

Properties

CommandPaletteAction.Id

CommandPaletteAction.Name

CommandPaletteAction.Subtitle

CommandPaletteAction.Keywords

CommandPaletteAction.Section

CommandPaletteAction.ParentId

CommandPaletteAction.Icon

CommandPaletteAction.Shortcut

CommandPaletteAction.IsEnabled

CommandPaletteAction.IsVisible

CommandPaletteAction.Perform

See also