292 lines
13 KiB
TypeScript
292 lines
13 KiB
TypeScript
/**
|
|
* What keys from a hardware keyboard do, apart from typing: the built-in
|
|
* defaults, the user's custom keybindings, and how the two combine.
|
|
*
|
|
* A key becomes one of the gestures the ring and the watch already have, so
|
|
* nothing downstream knows about keyboards. Three layers, first match wins:
|
|
*
|
|
* 1. Custom keybindings (Settings > Keyboard > Keybindings). These apply
|
|
* everywhere, including where the focused window takes keys for itself
|
|
* (a terminal session), since that is the point of binding a remote's
|
|
* few buttons.
|
|
* 2. Built-in bindings that also apply there: Escape with Shift, Ctrl or
|
|
* Alt goes back, which is the way out of a terminal session; and a
|
|
* mouse's buttons and wheel, which are never typed.
|
|
* 3. Built-in navigation, only for keys no window took: the arrows are the
|
|
* watch's four swipes, Enter selects, Escape goes back.
|
|
*
|
|
* A keyboard's touchpad or mouse arrives here as keys too: "MouseButton1"
|
|
* (left), "MouseButton2" (right), "MouseButton3" (middle) and so on, and
|
|
* "WheelUp" / "WheelDown" / "WheelLeft" / "WheelRight" (see pointer.ts).
|
|
*
|
|
* No platform imports: this runs under node in the tests.
|
|
*/
|
|
import type { KeyEvent } from "./keys";
|
|
|
|
/** A gesture a key can stand for, named as the input pipeline names it. */
|
|
export type KeyGesture =
|
|
| "swipe-up"
|
|
| "swipe-down"
|
|
| "swipe-left"
|
|
| "swipe-right"
|
|
| "scroll-up"
|
|
| "scroll-down"
|
|
| "click"
|
|
| "double-click"
|
|
| "long-press"
|
|
| "short-then-long-press";
|
|
|
|
/**
|
|
* What a custom keybinding does. "none" turns off the key's built-in
|
|
* navigation meaning; it does not stop the key being typed into a window
|
|
* that takes keys.
|
|
*/
|
|
export type KeyAction = KeyGesture | "none";
|
|
|
|
/** The actions, in the order the picker lists them. */
|
|
export const KEY_ACTIONS: readonly { action: KeyAction; label: string }[] = [
|
|
{ action: "click", label: "Select" },
|
|
{ action: "double-click", label: "Back" },
|
|
{ action: "swipe-up", label: "Swipe up" },
|
|
{ action: "swipe-down", label: "Swipe down" },
|
|
{ action: "swipe-left", label: "Swipe left" },
|
|
{ action: "swipe-right", label: "Swipe right" },
|
|
{ action: "scroll-up", label: "Scroll up" },
|
|
{ action: "scroll-down", label: "Scroll down" },
|
|
{ action: "long-press", label: "System menu" },
|
|
{ action: "short-then-long-press", label: "App menu" },
|
|
{ action: "none", label: "Nothing" },
|
|
];
|
|
|
|
export function keyActionLabel(action: KeyAction): string {
|
|
return KEY_ACTIONS.find((entry) => entry.action === action)?.label ?? action;
|
|
}
|
|
|
|
function isKeyAction(value: unknown): value is KeyAction {
|
|
return KEY_ACTIONS.some((entry) => entry.action === value);
|
|
}
|
|
|
|
/** A physical key with the modifiers held: what a keybinding is keyed on. */
|
|
export type KeyChord = { code: string; shift: boolean; ctrl: boolean; alt: boolean; meta: boolean };
|
|
export type KeyBinding = { chord: KeyChord; action: KeyAction };
|
|
|
|
const MODIFIER_CODES = new Set([
|
|
"ControlLeft", "ControlRight", "ShiftLeft", "ShiftRight", "AltLeft", "AltRight", "MetaLeft", "MetaRight",
|
|
]);
|
|
|
|
/** Shift, Ctrl, Alt and Meta themselves: they qualify a chord rather than being one. */
|
|
export function isModifierCode(code: string): boolean {
|
|
return MODIFIER_CODES.has(code);
|
|
}
|
|
|
|
export function chordOf(event: KeyEvent): KeyChord {
|
|
const { shift, ctrl, alt, meta } = event.modifiers;
|
|
return { code: event.code, shift, ctrl, alt, meta };
|
|
}
|
|
|
|
/** Canonical text of a chord ("Ctrl+Shift+Escape"): the stored form, and the lookup key. */
|
|
export function chordId(chord: KeyChord): string {
|
|
return [chord.ctrl && "Ctrl", chord.alt && "Alt", chord.shift && "Shift", chord.meta && "Meta", chord.code]
|
|
.filter(Boolean).join("+");
|
|
}
|
|
|
|
/** The inverse of chordId, or null for anything it could not have produced. */
|
|
export function parseChordId(text: string): KeyChord | null {
|
|
const parts = text.split("+");
|
|
const code = parts.pop() ?? "";
|
|
if (!/^[A-Za-z][A-Za-z0-9]{0,39}$/.test(code) || isModifierCode(code)) return null;
|
|
const chord: KeyChord = { code, shift: false, ctrl: false, alt: false, meta: false };
|
|
for (const part of parts) {
|
|
if (part === "Ctrl" && !chord.ctrl) chord.ctrl = true;
|
|
else if (part === "Alt" && !chord.alt) chord.alt = true;
|
|
else if (part === "Shift" && !chord.shift) chord.shift = true;
|
|
else if (part === "Meta" && !chord.meta) chord.meta = true;
|
|
else return null;
|
|
}
|
|
return chord;
|
|
}
|
|
|
|
const CODE_LABELS: Record<string, string> = {
|
|
ArrowUp: "Up", ArrowDown: "Down", ArrowLeft: "Left", ArrowRight: "Right",
|
|
Escape: "Esc", PageUp: "Page Up", PageDown: "Page Down", CapsLock: "Caps Lock",
|
|
PrintScreen: "Print Screen", ScrollLock: "Scroll Lock", NumLock: "Num Lock", ContextMenu: "Menu",
|
|
Minus: "-", Equal: "=", BracketLeft: "[", BracketRight: "]", Backslash: "\\", IntlBackslash: "\\",
|
|
IntlHash: "#", Semicolon: ";", Quote: "'", Backquote: "`", Comma: ",", Period: ".", Slash: "/",
|
|
AudioVolumeUp: "Volume Up", AudioVolumeDown: "Volume Down", AudioVolumeMute: "Mute",
|
|
MediaPlayPause: "Play/Pause", MediaPlay: "Play", MediaPause: "Pause", MediaStop: "Stop",
|
|
MediaTrackNext: "Next Track", MediaTrackPrevious: "Previous Track",
|
|
BrightnessUp: "Brightness Up", BrightnessDown: "Brightness Down",
|
|
BrowserSearch: "Search", BrowserHome: "Browser Home", BrowserBack: "Browser Back", BrowserForward: "Browser Forward",
|
|
LaunchMail: "Mail", LaunchApplication1: "App 1", LaunchApplication2: "App 2",
|
|
MouseButton1: "Left button", MouseButton2: "Right button", MouseButton3: "Middle button",
|
|
WheelUp: "Wheel up", WheelDown: "Wheel down", WheelLeft: "Wheel left", WheelRight: "Wheel right",
|
|
};
|
|
|
|
/** A key as a person would name it. Unknown keys keep their HID usage number, which is all there is. */
|
|
function codeLabel(code: string): string {
|
|
const known = CODE_LABELS[code];
|
|
if (known) return known;
|
|
let match = /^Key([A-Z])$/.exec(code);
|
|
if (match) return match[1]!;
|
|
match = /^Digit([0-9])$/.exec(code);
|
|
if (match) return match[1]!;
|
|
match = /^Numpad(.+)$/.exec(code);
|
|
if (match) return `Numpad ${match[1]}`;
|
|
match = /^MouseButton([0-9]+)$/.exec(code);
|
|
if (match) return `Mouse button ${match[1]}`;
|
|
match = /^Usage([0-9a-f]+)$/.exec(code);
|
|
if (match) return `Key 0x${match[1]}`;
|
|
match = /^Consumer([0-9a-f]+)$/.exec(code);
|
|
if (match) return `Media key 0x${match[1]}`;
|
|
return code;
|
|
}
|
|
|
|
/** A chord for display: "Shift+Esc", "Left", "Volume Up". */
|
|
export function describeChord(chord: KeyChord): string {
|
|
return [chord.ctrl && "Ctrl", chord.alt && "Alt", chord.shift && "Shift", chord.meta && "Meta", codeLabel(chord.code)]
|
|
.filter(Boolean).join("+");
|
|
}
|
|
|
|
/** The most custom keybindings kept; far more than a keyboard has uses for. */
|
|
export const MAX_KEY_BINDINGS = 64;
|
|
|
|
/**
|
|
* Custom keybindings from their stored JSON. Lenient: whatever doesn't make
|
|
* sense is dropped, and a later entry for a chord replaces an earlier one.
|
|
*/
|
|
export function parseKeyBindings(raw: string): KeyBinding[] {
|
|
let parsed: unknown;
|
|
try {
|
|
parsed = raw ? JSON.parse(raw) : [];
|
|
} catch {
|
|
return [];
|
|
}
|
|
if (!Array.isArray(parsed)) return [];
|
|
const bindings = new Map<string, KeyBinding>();
|
|
for (const entry of parsed) {
|
|
if (!entry || typeof entry !== "object") continue;
|
|
const { key, action } = entry as { key?: unknown; action?: unknown };
|
|
const chord = typeof key === "string" ? parseChordId(key) : null;
|
|
if (!chord || !isKeyAction(action)) continue;
|
|
bindings.set(chordId(chord), { chord, action });
|
|
if (bindings.size >= MAX_KEY_BINDINGS) break;
|
|
}
|
|
return [...bindings.values()];
|
|
}
|
|
|
|
export function serializeKeyBindings(bindings: readonly KeyBinding[]): string {
|
|
return JSON.stringify(bindings.map((binding) => ({ key: chordId(binding.chord), action: binding.action })));
|
|
}
|
|
|
|
/** Custom keybindings as the lookup resolveKey takes. */
|
|
export function keyBindingMap(bindings: readonly KeyBinding[]): Map<string, KeyAction> {
|
|
return new Map(bindings.map((binding) => [chordId(binding.chord), binding.action]));
|
|
}
|
|
|
|
/** What a mouse does unless bound otherwise: the ring's tap, double tap, hold and scroll. */
|
|
const MOUSE_DEFAULTS: Record<string, KeyGesture | undefined> = {
|
|
MouseButton1: "click",
|
|
MouseButton2: "double-click",
|
|
MouseButton3: "long-press",
|
|
WheelUp: "scroll-up",
|
|
WheelDown: "scroll-down",
|
|
};
|
|
|
|
/**
|
|
* The built-in meaning of a key press, or null when it has none.
|
|
* `overridesTyping`: it holds even where the focused window takes keys.
|
|
* Built-ins go by the logical key, so both Enter keys select.
|
|
*/
|
|
export function defaultKeyAction(event: KeyEvent): { action: KeyGesture; overridesTyping: boolean } | null {
|
|
// A mouse's buttons and wheel are the ring's gestures: tap, double tap,
|
|
// hold, and scroll. Nothing types them, so they hold everywhere, whatever
|
|
// is held on the keyboard.
|
|
const mouse = MOUSE_DEFAULTS[event.key];
|
|
if (mouse) return { action: mouse, overridesTyping: true };
|
|
const { shift, ctrl, alt, meta } = event.modifiers;
|
|
if (meta) return null;
|
|
if (event.key === "Escape") {
|
|
// Plain Escape belongs to whatever takes keys (it is a keystroke in a
|
|
// terminal); with a modifier it always means "back out of here".
|
|
return { action: "double-click", overridesTyping: shift || ctrl || alt };
|
|
}
|
|
if (ctrl || alt) return null;
|
|
switch (event.key) {
|
|
case "ArrowUp":
|
|
return { action: "swipe-up", overridesTyping: false };
|
|
case "ArrowDown":
|
|
return { action: "swipe-down", overridesTyping: false };
|
|
case "ArrowLeft":
|
|
return { action: "swipe-left", overridesTyping: false };
|
|
case "ArrowRight":
|
|
return { action: "swipe-right", overridesTyping: false };
|
|
case "Enter":
|
|
return { action: "click", overridesTyping: false };
|
|
default:
|
|
return null;
|
|
}
|
|
}
|
|
|
|
/** The built-ins, for showing to the user. Keep in step with defaultKeyAction. */
|
|
export const DEFAULT_KEYS_HELP =
|
|
"Arrow keys: swipe up, down, left and right, as on the watch. Enter: select. Esc: back.\n\n" +
|
|
"In a terminal session those keys are typed instead, and Shift+Esc (or Ctrl+Esc, Alt+Esc) goes back.\n\n" +
|
|
"Mouse or touchpad: the left button selects, the right button goes back, the middle button opens the system menu, " +
|
|
"and the wheel scrolls. These work in a terminal session too.\n\n" +
|
|
"A custom keybinding replaces these for its key and works everywhere, terminals included. " +
|
|
"\"Nothing\" turns a key's meaning here off without stopping it being typed.";
|
|
|
|
/**
|
|
* Whether holding the key repeats the gesture. Moving up and down a list
|
|
* does. Sideways swipes don't: depending on the layout they enter and leave
|
|
* things, and a held key would flap between the two. Selecting, backing out
|
|
* and menus act once per press.
|
|
*/
|
|
export function gestureRepeats(gesture: KeyGesture): boolean {
|
|
return gesture === "scroll-up" || gesture === "scroll-down" || gesture === "swipe-up" || gesture === "swipe-down";
|
|
}
|
|
|
|
export type KeyResolution = {
|
|
/** The key is spoken for: don't offer it to the focused window. */
|
|
consume: boolean;
|
|
/**
|
|
* The gesture to perform: at once when `consume`, otherwise only if no
|
|
* window takes the key. Null for none (including a held key's repeats of
|
|
* a gesture that doesn't repeat).
|
|
*/
|
|
gesture: KeyGesture | null;
|
|
};
|
|
|
|
/** What one key press (or auto-repeat) means, given the custom keybindings. */
|
|
export function resolveKey(event: KeyEvent, custom: ReadonlyMap<string, KeyAction>): KeyResolution {
|
|
const repeatable = (gesture: KeyGesture): KeyGesture | null =>
|
|
event.repeat && !gestureRepeats(gesture) ? null : gesture;
|
|
const bound = custom.get(chordId(chordOf(event)));
|
|
if (bound !== undefined && bound !== "none") return { consume: true, gesture: repeatable(bound) };
|
|
// "none" takes the built-in meaning away and leaves the key to be typed.
|
|
if (bound === "none") return { consume: false, gesture: null };
|
|
const builtIn = defaultKeyAction(event);
|
|
if (!builtIn) return { consume: false, gesture: null };
|
|
return { consume: builtIn.overridesTyping, gesture: repeatable(builtIn.action) };
|
|
}
|
|
|
|
export type GestureOrigin = "ring" | "watch";
|
|
|
|
/**
|
|
* Which device a keyboard's gesture is presented as. Swipes are the watch's
|
|
* and scrolls the ring's; the two schemes differ in places (an icon grid
|
|
* moves by cell for the watch, by row and then cell for the ring). A tap, a
|
|
* double tap or a hold exists in both, so it goes with whichever the
|
|
* keyboard last moved with: arrow keys make the keyboard a watch, a remote
|
|
* bound to scroll makes it a ring. Before any movement, the watch.
|
|
*/
|
|
export class GestureScheme {
|
|
private scheme: GestureOrigin = "watch";
|
|
|
|
originFor(gesture: KeyGesture): GestureOrigin {
|
|
if (gesture.startsWith("swipe-")) this.scheme = "watch";
|
|
else if (gesture.startsWith("scroll-")) this.scheme = "ring";
|
|
return this.scheme;
|
|
}
|
|
}
|