Keyboard shortcuts

Summary

A key-sequence registry for power users: single keys, multi-key sequences (g then d), and modifier combos. One document-level listener serves every binding. Shortcuts never fire while an input, textarea, select or contenteditable has focus, nor while a modal dialog is open — so they can't hijack typing.

When to use

Pattern	Use it for
Single key	The one or two most frequent actions on a page, such as `c` to create.
Sequence	Navigation namespaces: `g` `d` "go to dashboard", `g` `p` "go to projects".
Modifier combo	Actions inside a form or editor, where bare letters would be typing (`ctrl`+`return` to submit).
`moveToNextItem`	List traversal: `j`/`k` over rows, feeds, findings.

Examples

Try them with focus outside a field:

t show a toast
g then h “go home” (toast instead of navigating)
ctrl+return submit-style action
j / k move down/up the list →

JavaScript

Soma.shortcuts('gd').or('gh').goTo('/dashboard');
Soma.shortcuts('c').click('#create');
Soma.shortcuts('j').moveToNextItem('.issue');
Soma.shortcuts('k').moveToPrevItem('.issue');
Soma.shortcuts('ctrl+return').execute((e) => form.submit());

const sc = Soma.shortcuts('x').execute(fn);
sc.unbind();   // remove it again

Member	Description
`Soma.shortcuts(keys)`	Bind a sequence. `"gd"` = g then d; `"gh gd"` = two alternatives; modifiers chain with `+`.
`.or(keys)`	Add another sequence for the same action.
`.execute(fn)`	Run a callback.
`.click(sel)` / `.moveToAndClick(sel)`	Activate a control; `moveToAndClick` scrolls it into view first. Both annotate the target's `title` so the shortcut is discoverable.
`.moveToAndFocus(sel)` / `.followLink(sel)` / `.goTo(url)`	Focus a control, follow a link, or navigate.
`.moveToNextItem(sel, opts)` / `.moveToPrevItem(...)`	Walk a collection, marking the current one (`focusedClass`, default `soma-focused`; `wrapAround` default true).
`.unbind()`	Remove the binding and its title annotations.
`Soma.shortcutsFromJSON(list)`	Declarative form for plugin descriptors: `[{keys: [["g","d"]], op: "goTo", param: "/dashboard"}]`.

Key names

Letters and digits are literal. Multi-character names: return (Enter), esc, space, del, tab, backspace, home, end, pageup, pagedown, left/right/up/down, f1–f12. Modifiers: ctrl, meta, shift, alt. Sequences reset after one second of inactivity.