A free, open source, and extensible speech-to-text application that works completely offline.
/**
* Keyboard utility functions for handling keyboard events
*/
import type { KeyboardEvent as ReactKeyboardEvent } from "react";
export type OSType = "macos" | "windows" | "linux" | "unknown";
/** IME boundary keydowns can have isComposing=false while keyCode is still 229. */
export const isComposingKeyEvent = (
event: Pick<KeyboardEvent, "isComposing" | "keyCode">,
): boolean => event.isComposing || event.keyCode === 229;
const keepSpace = (e: ReactKeyboardEvent<HTMLElement>) => {
if (e.key === " ") e.preventDefault();
};
/** Spread on shortcut controls so a Space in the shortcut doesn't click them. */
export const spaceDoesNotClick = { onKeyDown: keepSpace, onKeyUp: keepSpace };
// Shortcut parsers require compact tokens; keep display labels separate.
const COMPOUND_KEY_DISPLAY: Record<string, string> = {
capslock: "Caps Lock",
numlock: "Num Lock",
pageup: "Page Up",
pagedown: "Page Down",
printscreen: "Print Screen",
scrolllock: "Scroll Lock",
};
/**
* Extract a consistent key name from a KeyboardEvent
* This function provides cross-platform keyboard event handling
* and returns key names appropriate for the target operating system
*/
export const getKeyName = (
e: KeyboardEvent,
osType: OSType = "unknown",
): string => {
// Handle special cases first
if (e.code) {
const code = e.code;
// Handle function keys (F1-F24)
if (code.match(/^F\d+$/)) {
return code.toLowerCase(); // F1, F2, ..., F14, F15, etc.
}
// Handle regular letter keys (KeyA -> a)
if (code.match(/^Key[A-Z]$/)) {
return code.replace("Key", "").toLowerCase();
}
// Handle digit keys (Digit0 -> 0)
if (code.match(/^Digit\d$/)) {
return code.replace("Digit", "");
}
// Handle numpad digit keys (Numpad0 -> numpad 0)
if (code.match(/^Numpad\d$/)) {
return code.replace("Numpad", "numpad ").toLowerCase();
}
// Handle modifier keys - OS-specific naming
const getModifierName = (baseModifier: string): string => {
switch (baseModifier) {
case "shift":
return "shift";
case "ctrl":
return osType === "macos" ? "ctrl" : "ctrl";
case "alt":
return osType === "macos" ? "option" : "alt";
case "meta":
// Windows key on Windows/Linux, Command key on Mac
if (osType === "macos") return "command";
return "super";
default:
return baseModifier;
}
};
const modifierMap: Record<string, string> = {
ShiftLeft: getModifierName("shift"),
ShiftRight: getModifierName("shift"),
ControlLeft: getModifierName("ctrl"),
ControlRight: getModifierName("ctrl"),
AltLeft: getModifierName("alt"),
AltRight: getModifierName("alt"),
MetaLeft: getModifierName("meta"),
MetaRight: getModifierName("meta"),
OSLeft: getModifierName("meta"),
OSRight: getModifierName("meta"),
CapsLock: "capslock",
Tab: "tab",
Enter: "enter",
Space: "space",
Backspace: "backspace",
Delete: "delete",
Escape: "esc",
ArrowUp: "up",
ArrowDown: "down",
ArrowLeft: "left",
ArrowRight: "right",
Home: "home",
End: "end",
PageUp: "pageup",
PageDown: "pagedown",
Insert: "insert",
PrintScreen: "printscreen",
ScrollLock: "scrolllock",
Pause: "pause",
ContextMenu: "menu",
NumpadMultiply: "numpad *",
NumpadAdd: "numpad +",
NumpadSubtract: "numpad -",
NumpadDecimal: "numpad .",
NumpadDivide: "numpad /",
NumLock: "numlock",
};
if (modifierMap[code]) {
return modifierMap[code];
}
// Handle punctuation and special characters
const punctuationMap: Record<string, string> = {
Semicolon: ";",
Equal: "=",
Comma: ",",
Minus: "-",
Period: ".",
Slash: "/",
Backquote: "`",
BracketLeft: "[",
Backslash: "\\",
BracketRight: "]",
Quote: "'",
};
if (punctuationMap[code]) {
return punctuationMap[code];
}
// Parser names mirror KeyboardEvent.code without spaces.
return code.toLowerCase();
}
// Fallback to e.key if e.code is not available
if (e.key) {
const key = e.key;
// Handle special key names with OS-specific formatting
const keyMap: Record<string, string> = {
Control: osType === "macos" ? "ctrl" : "ctrl",
Alt: osType === "macos" ? "option" : "alt",
Shift: "shift",
Meta:
osType === "macos" ? "command" : osType === "windows" ? "win" : "super",
OS:
osType === "macos" ? "command" : osType === "windows" ? "win" : "super",
CapsLock: "capslock",
ArrowUp: "up",
ArrowDown: "down",
ArrowLeft: "left",
ArrowRight: "right",
Escape: "esc",
" ": "space",
};
if (keyMap[key]) {
return keyMap[key];
}
return key.toLowerCase();
}
// Last resort fallback
return `unknown-${e.keyCode || e.which || 0}`;
};
/**
* Capitalize a key name for display (e.g. "space" -> "Space", "f1" -> "F1")
*/
const capitalizeKey = (key: string): string => {
// fn key: keep lowercase
if (key === "fn") return "fn";
// Function keys: f1 -> F1
if (/^f\d+$/.test(key)) return key.toUpperCase();
// Single char: a -> A
if (key.length === 1) return key.toUpperCase();
if (COMPOUND_KEY_DISPLAY[key]) return COMPOUND_KEY_DISPLAY[key];
// Multi-word: capitalize first letter of each word
return key.replace(/\b\w/g, (c) => c.toUpperCase());
};
/**
* Format a single key part for display.
* Handles _left/_right suffixes and capitalizes names.
* e.g. "shift_left" -> "Left Shift", "option" -> "Option", "space" -> "Space"
*/
const formatKeyPart = (part: string): string => {
const trimmed = part.trim();
if (!trimmed) return "";
if (trimmed.endsWith("_left")) {
const name = trimmed.slice(0, -5);
return `Left ${capitalizeKey(name)}`;
}
if (trimmed.endsWith("_right")) {
const name = trimmed.slice(0, -6);
return `Right ${capitalizeKey(name)}`;
}
return capitalizeKey(trimmed);
};
/**
* Get display-friendly key combination string for the current OS
* Formats raw hotkey strings like "option_left+shift+space" into
* human-readable form like "Left Option + Shift + Space"
*/
export const formatKeyCombination = (
combination: string,
_osType: OSType,
): string => {
if (!combination) return "";
return combination.split("+").map(formatKeyPart).join(" + ");
};
/**
* Normalize modifier keys to handle left/right variants
*/
export const normalizeKey = (key: string): string => {
// Handle left/right variants of modifier keys
if (key.startsWith("left ") || key.startsWith("right ")) {
const parts = key.split(" ");
if (parts.length === 2) {
// Return just the modifier name without left/right prefix
return parts[1];
}
}
return key;
};
/** Keys that only modify another: a binding needs a key besides these. */
export const MODIFIERS = [
"ctrl",
"control",
"shift",
"alt",
"option",
"meta",
"command",
"cmd",
"super",
"win",
"windows",
"fn",
];
/** The keys in a binding, or in one still being captured ("option+space"). */
export const bindingKeys = (binding: string | null | undefined): string[] =>
binding ? binding.split("+").filter(Boolean) : [];
/** Only modifiers are held so far: the binding still needs a key. */
export const isOnlyModifiers = (keys: string[]): boolean =>
keys.length > 0 && keys.every((k) => MODIFIERS.includes(k.toLowerCase()));
// Labels as printed on the keys; a key's side (option_left) isn't printed.
const MAC_KEYCAPS: Record<string, string> = {
option: "⌥",
alt: "⌥",
command: "⌘",
cmd: "⌘",
meta: "⌘",
super: "⌘",
ctrl: "⌃",
control: "⌃",
shift: "⇧",
};
const PC_KEYCAPS: Record<string, string> = {
alt: "Alt",
option: "Alt",
ctrl: "Ctrl",
control: "Ctrl",
shift: "Shift",
meta: "⊞",
super: "⊞",
command: "⊞",
};
/** "option+space" → ["⌥", "Space"] on macOS. */
export const keycapLabels = (binding: string, osType: OSType): string[] =>
binding
.split("+")
.map((part) => part.trim())
.filter(Boolean)
.map((part) => {
const key = part.replace(/_(left|right)$/, "");
const glyphs = osType === "macos" ? MAC_KEYCAPS : PC_KEYCAPS;
return glyphs[key] ?? capitalizeKey(key);
});
/** "⌥ Space" on macOS, "Alt + Space" elsewhere. */
export const keycapLabel = (binding: string, osType: OSType): string =>
keycapLabels(binding, osType).join(osType === "macos" ? " " : " + ");