Keyboard

Add attaches a global keydown shortcut and returns a Guid you can later pass to Remove. By default the browser action is suppressed (preventDefault and stopPropagation are true) and held keys do not auto-repeat - except that a shortcut without Ctrl, Alt or Meta stands aside while its key goes to a control that acts on it, see below. Two shortcuts are live on this page right now.

@inject Bit.Butil.Keyboard keyboard

@code {
    private Guid ctrlKId;

    protected override async Task OnInitializedAsync()
    {
        ctrlKId = await keyboard.Add(ButilKeyCodes.KeyK, () =>
        {
            // open your command palette...
        }, ButilModifiers.Ctrl);

        await keyboard.Add(ButilKeyCodes.F9, () => { /* ... */ });
    }
}

ButilModifiers is a flags enum - combine Ctrl, Alt, Shift and Meta with the bitwise or operator. Build a shortcut below and register it live; press it to see it fire, and register a new one to replace it.

await keyboard.Add(ButilKeyCodes.KeyU,
    () => { /* ... */ },
    ButilModifiers.Ctrl | ButilModifiers.Shift);

Subscribe is Add with lifecycle sugar: it returns a ButilSubscription whose DisposeAsync detaches the shortcut, so a component can await-using a shortcut or dispose it in DisposeAsync without tracking Guids.

private ButilSubscription? shortcut;

shortcut = await keyboard.Subscribe(ButilKeyCodes.KeyB, () =>
{
    // toggle the sidebar...
}, ButilModifiers.Ctrl);

// later:
await shortcut.DisposeAsync();

SubscribeOn binds the shortcut to a specific element: the handler only fires while that element (or one of its descendants) receives the keyboard event. Perfect for editor areas that need their own key handling without hijacking the whole page. The element a shortcut is scoped to never makes it stand aside for IgnoreWhenEditable, only the controls inside it - so a shortcut scoped to a text field fires while the user types there.

<textarea @ref="editorRef"></textarea>

@code {
    private ElementReference editorRef;
    private ButilSubscription? editorShortcut;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender is false) return;

        editorShortcut = await keyboard.SubscribeOn(editorRef,
            ButilKeyCodes.Enter, () => { /* submit */ }, ButilModifiers.Ctrl);
    }
}

preventDefault defaults to true, so a shortcut on a key a control also acts on would take that key away from every control on the page. A shortcut without Ctrl, Alt or Meta therefore stands aside, by default, while its key goes to such a control - nothing fired, nothing suppressed, the key does what it always does there. The test is per key: Delete in a text field deletes text, but Delete on a select, which has no use for it, still fires the shortcut; ArrowRight moves the slider and the caret, but fires on the checkbox. IgnoreWhenEditable sets it explicitly: true stands aside whatever the modifiers, false never does. Register both shortcuts below, then press Delete and ArrowRight on each control - once with the default, once with false.

// Deletes the selected rows - but never the text being typed in a search box.
// Delete has no Ctrl, Alt or Meta, so it stands aside by default.
await keyboard.Add(ButilKeyCodes.Delete, () => { /* delete the selection */ });

// A modified shortcut stays live in text fields unless told otherwise -
// here the field's own undo wins while the user is typing.
await keyboard.Add(ButilKeyCodes.KeyZ, () => { /* undo the last row edit */ },
    new KeyboardShortcutOptions { Modifiers = ButilModifiers.Ctrl, IgnoreWhenEditable = true });

// Take Delete from every control on the page instead.
await keyboard.Add(ButilKeyCodes.Delete, () => { /* ... */ },
    new KeyboardShortcutOptions { IgnoreWhenEditable = false });

Remove(Guid) detaches one shortcut by the id Add returned. Remove(Action) matches by delegate identity and returns the removed ids. RemoveAll wipes every shortcut registered through this Keyboard instance.

var id = await keyboard.Add(ButilKeyCodes.F9, handler);

await keyboard.Remove(id);        // by id (recommended)
await keyboard.Remove(handler);   // by the exact same delegate instance
await keyboard.RemoveAll();       // everything on this Keyboard instance

ButilKeyCodes provides string constants for every physical key: letters (KeyA-KeyZ), digits (Digit0-Digit9), the numpad, function keys (F1-F12), navigation, editing and symbol keys. They are plain KeyboardEvent.code values, so any valid code string works too.

ButilKeyCodes.KeyK        // "KeyK"
ButilKeyCodes.Digit1      // "Digit1"
ButilKeyCodes.F9          // "F9"
ButilKeyCodes.Enter       // "Enter"
ButilKeyCodes.Escape      // "Escape"
ButilKeyCodes.ArrowDown   // "ArrowDown"
ButilKeyCodes.NumpadAdd   // "NumpadAdd"
ButilKeyCodes.Backquote   // "Backquote"