Allow for Custom Keybindings & Keyboard Shortcuts

[BrianHung]

For the app I'm integrating glide-data-grid into, we need some custom keyboard shortcuts

• ctrl / cmd + arrowkey moves selection to the first cell with content in the direction pressed
• tab (and shift tab) moves selection in between instances of glide-data-grid

Implementing either would involve overwriting default behavior (although tab behavior is not documented in keybindings), and essentially having glide-data-grid support custom keyboard shortcuts.

Two ideas I want to propose:

• a new onKeyDown prop that takes priority over keybindings in data-editor
• separating keybindings into keymap and commands

---

For the first idea, the current onKeyDown looks like

glide-data-grid/packages/core/src/data-editor/data-editor.tsx

Lines 1713 to 1718 in 0e62b1c

	const onKeyDown = React.useCallback(
	(event: GridKeyEventArgs) => {
	const fn = async () => {
	const overlayOpen = overlay !== undefined;
	const { altKey, shiftKey } = event;
	const isOSX = browserIsOSX.value;

where keybindings are checked and ran.

To support a onKeyDown prop, we can have

readonly onKeyDown?: (event: GridKeyEventArgs, ctx: DataEditorContent) => boolean;

    const onKeyDown = React.useCallback(
        (event: GridKeyEventArgs) => {
            const fn = async () => {
                // If handled by prop onKeyDown, just return.
                if (props.onKeyDown?.(event, ctx)) return;

---

The second idea is a bit more work and is inspired by how ProseMirror, a text editor framework, allows for developers to implement custom keyboard behavior:

https://prosemirror.net/docs/ref/#keymap
https://prosemirror.net/docs/ref/#commands

It essentially splits the concept of keyboard shortcuts into two concepts:

• commands, which aren't bounded to specific key bindings, define editing actions e.g. fillDown and deleteRange
• keymaps, which map shortcuts to commands, e.g. "Mod+ArrowDown": fillDown

The benefit of this over the current keybindings prop is customizability and re-usability. For example,

// Right now
keybindings={{
  downFill: true
  // undo? hard to implement within `glide-data-grid` since collaborative state might be involved
}}

// With this idea
keymap={{
  "Mod+d": downFill // downFill can be exported by `glide-data-grid`
  // "Mod+z": undo where undo is tied to how developer is handling state
}}

and

// Could be used by "Mod+a", top left corner click, external component
dataGridRef.commands.selectAll()

Note that the second idea is not exclusive with the first one: the first one would be prioritized over keymaps and commands as ProseMirror does: https://prosemirror.net/docs/ref/#view.EditorProps.handleKeyDown.

[BrianHung]

Noticed there's an emit imperative function in data-editor.

glide-data-grid/packages/core/src/data-editor/data-editor.tsx

Lines 2327 to 2381 in 0e62b1c

	React.useImperativeHandle(
	forwardedRef,
	() => ({
	updateCells: (...args) => gridRef.current?.damage(...args),
	getBounds: (...args) => gridRef.current?.getBounds(...args),
	emit: async e => {
	switch (e) {
	case "delete":
	onKeyDown({
	bounds: undefined,
	cancel: () => undefined,
	ctrlKey: false,
	key: "Delete",
	keyCode: 46,
	metaKey: false,
	shiftKey: false,
	altKey: false,
	});
	break;
	case "fill-right":
	onKeyDown({
	bounds: undefined,
	cancel: () => undefined,
	ctrlKey: true,
	key: "r",
	keyCode: 82,
	metaKey: false,
	shiftKey: false,
	altKey: false,
	});
	break;
	case "fill-down":
	onKeyDown({
	bounds: undefined,
	cancel: () => undefined,
	ctrlKey: true,
	key: "d",
	keyCode: 68,
	metaKey: false,
	shiftKey: false,
	altKey: false,
	});
	break;
	case "copy":
	await onCopy();
	break;
	case "paste":
	await onPasteInternal();
	break;
	}
	},
	scrollTo,
	}),
	[onCopy, onKeyDown, onPasteInternal, scrollTo]
	);

That could be replaced by commands in the second idea.

// Right now
dataGridRef.emit("delete")

// With commands
dataGridRef.commands.delete(gridSelection)

[jassmith]

The imperative commands are there for you to handle these yourself if you want. Are they not good enough for that?

[jassmith]

seems like you could do something like

<DataEditor 
  keybindings={{
    selectAll: "ctrl+shift+a"
  }};
/>

but I'm still stuck with this dumb keybinding description language which I don't want to be stuck with so the next thing I thought was

<DataEditor 
  keybindings={{
    selectAll: {
      key: "a",
      code: 64,
      shift: true,
      ctrl: true
    }
  }};
/>

It's more verbose but then we don't have to write a parser. We can instead let you farm that out to something else.

[jassmith]

Obviously if you pass a custom keybind for something in the keybindings collection it is the same as passing true and setting the shortcut.

[BrianHung]

still stuck with this dumb keybinding description language which I don't want to be stuck

If it helps, I've seen other libraries that deal with keyboard shortcuts have something similar: https://github.com/ccampbell/mousetrap

It's more verbose but then we don't have to write a parser.

I think a simple parser (?) will always been involved, since you need a way to check if a keyboard event has a shortcut event associated with it. Edit: Realized its opposite of a parser.. a flattener? normalizer?

And the way to do that is usually through "normalizing" it via (event: KeyboardEvent) => (key: string) where the key is used later t o index into shortcuts = Record<key, Function>.

That's essentially what this line does from prosemirror-keymap

It's also why maybe for keybindings, the keys should be the normalized key event instead of the shortcut; otherwise' you'd have to iterate through all shortcuts and their keybindings.

Another benefit of using normalized key events as the key is you could register multiple commands to the same keybinding, with the priority being the order of the array and breaking on first command that returns true.

const key = normalized(event)
const commands = shortcuts[key]
for (let i = 0; i < commands.length; i++) {
  if (commands[i](context) === true)
    break;
}

I think this is more manageable than having multiple ifs or switch statements since the amount of possible keybindings is innumerable.

[jassmith]

oh I mean the way I handle keybindings right now is definitely not scalable. We would definitely want to build a normalized lookup table. That is orthogonal to if we want to support string based keybinds or object syntax for them. The user in me wants strings, the maintainer in me dreads the strings. The problem with string syntax is how do you support things like keycodes vs key? Ctrl + Shift + D produces key "D" where as ctrl + d produces key "d" and uhg why can't I be working in C again...

KeyboardEvent.code would work but nobody wants to write "ctrl+shift+KeyD" and how does "shift+`" map correctly?

All that whining out of the way, I think the only thing that makes sense is to make the parsing very dumb and thus unlikely to bite us in the butt. Spec by example only:

• alt+KeyD -> Alt + D
• primary+KeyD -> Command + D on mac, Ctrl + D on windows
• ctrl+shift -> error
• ctrl+alt+shift+Backsquote -> Ctrl + Alt + Shift + `
• primary+alt+Delete -> ctrl + alt + del on windows, command + alt + del on mac

No idea if there is a better name for primary. No idea if we should omit that. Not sure if we should allow lower casing, its possible that causes conflict because I don't know the entire keymap by heart. If it does, whoever made that is a jackass.

[BrianHung]

Ctrl + Shift + D produces key "D" where as ctrl + d produces key "d"

I've ran into a similar problem before but with caps lock (browsers are inconsistent + international keyboards) 😅
https://discuss.prosemirror.net/t/undo-redo-broken-with-caps-lock-on-website-demo/4068
ProseMirror/prosemirror#895

nobody wants to write "ctrl+shift+KeyD" and how does "shift+`" map correctly

I don't think the syntax is that bad e.g. https://github.com/ProseMirror/prosemirror-commands/blob/6fda4b50a13df239db73395c16eef5a1d2795609/src/commands.js#L637-L662 but i've been stuck in text editor land too long

make the parsing very dumb and thus unlikely to bite us in the butt

Agreed

No idea if there is a better name for primary.

prosemirror-keymap supports this concept by calling it a Mod(ifier) key: https://github.com/ProseMirror/prosemirror-keymap/blob/bcc8280e38900edeb6ed946e496ad7dbc0c17f95/src/keymap.js#L8-L26

If you want to target ctrl or cmd specifically, you can write "Ctrl+" and "Cmd+".

[arogozhnikov]

Hi @BrianHung, did you manage to implement these shortcuts?
If so, do you mind sharing? I'm currently stuck at getting and changing current selection (I see no way to do this when having only gridRef).

[arogozhnikov]

You mean, use onGridSelectionChange to store the copy of a current selection in a parent component. Did I understand what you suggest?

[BrianHung]

Hm, what are you trying to do with current selection?

onGridSelectionChange to store the copy of a current selection in a parent component

Yes, so control grid selection in your React component.

const [gridSelection, setGridSelection] = useState(...)

[arogozhnikov]

Suppose E7 is selected, and contains an integer. I need a shortcut that fills E8 with the next integer, and moves selection to E8, so that operation can be repeated

[BrianHung]

I would modify your data source and gridSelection in your parent component. This example doesn't need any additional changes to glide.

[arogozhnikov]

that's what I ended up doing. Seems to work ok