Upcoming changes to keymap.json

[ConradIrwin]

Keymap JSON changes

The current keymap JSON suffers from a few notable deficiencies:

• The array syntax for arguments is non-standard and gets in the way of a desire to add sequences of actions.
• The context field is very confusing, in particular > and ! do not act as people hope they would.
• workspace::SendKeystrokes is pretty meh for such an important feature.
• Keystrokes cannot be reliably disabled if cx.propagate() is called.

Over the next few releases we hope to fix these similarly to how it's described below. For some changes we should be able to automatically migrate your keymap file, but for others (particularly tweaks to the context) we may need to leave things as is. Luckily we don't expect the context changes to do anything except fix existing broken keymaps.

Arguments

To fix the arguments we should use JSON object syntax instead of array syntax:

// before
"1": ["vim::Number", 1]
// after
"1": {"action": "vim::Number", "digit": 1}
Though more verbose for un-named parameters this format matches exactly how tagged enums usually are represented in JSON.

For actions with named arguments, the advantage is clearer:

// before
"ctrl-k u": ["pane::CloseCleanItems", { "close_pinned": false }],
// after 
"ctrl-k u": {"action": "pane::CloseCleanItems", "close_pinned": false}
This does necessitate naming the arguments for actions.

Mappings

I added the workspace::SendKeystrokes action as a way to map from one key sequence to another. This feature is common enough that it should get its own syntax:

// before
"j k": ["workspace::SendKeystrokes", "escape"]
// after
"j k": {"keystrokes": "escape"}
Context changes

We might want to consider a deeper change here, but assuming we want to keep roughly the model we have today, it’s necessary to fix a few things:

• should mean “ancestor” not “parent”, so that for example you can bind to debugger_stopped > vim_mode == normal instead of debugger_stopped > Pane > vim_mode == normal.

• !X should mean “no ancestor matches X”, not “all ancestors don’t match X”, so that you can do !Terminal && !Editor instead of having to list every context you don’t care about.

Disabling

I'm less sure how to fix this. Today you can disable a binding in a matching context by assigning it to null. However, this isn't always sufficient to do what you want. (c.f. #20167).

Cases that don't seem to work well today:

• Disabling an action that calls cx.propagate(). For example if you want ctrl-g to act as escape in the editor, you can't because escape calls cx.propagate() which means that ctrl-g will still act as go-to-line.
• Disabling a specific action on a keybinding so that your overridden action can still work.

One option would be to make disabling about the action(s) you don't want to happen instead of the key-binding:

// before
"ctrl-g": null // doesn't actually work
// after
"ctrl-g": {"disable": ["editor::GoToLine"]}

Open to more ideas here though!

[JonGretar]

I'm not bothered with the syntax of binding to null. It just needs badly to change what it means. I would have thought that it makes it appear like the key binding does not exist(given that I bound it in the same context as the default binding) but instead it seems to bind to a null action. And thus can have presidence. This makes no sense and forces me to bind define a keymap twice in two different contexts.

[JonGretar]

I do hope this means that we will get the ability to bind to a sequences of actions soo. Although how it works exactly should be discussed. For example are tasks run parallel or sequentially. Is it required that action 1 succeeds before action 2 runs.