Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

3.7 KB
Raw Blame
/**
 * Every app-wide keyboard shortcut, in one place.
 *
 * One place on purpose: the binding a listener matches against and the combo the settings page
 * shows a person are the same entry, so they cannot drift apart. Adding a shortcut is adding an
 * entry here and one `useHotkey` call where it acts; the settings list picks it up by itself.
 *
 * Browsers reserve their own combos. Cmd/Ctrl+N — the obvious key for "new chat" — opens a new
 * browser window before the page ever sees the keystroke, and `preventDefault` is ignored for
 * reserved shortcuts, so no entry here can use one. Plain Shift+letter combos work everywhere,
 * at the cost that they are also just how capital letters are typed — which is why `useHotkey`
 * ignores them while focus is in anything editable.
 */

export type HotkeyCombo = {
  /** KeyboardEvent.key, lowercase. */
  key: string;
  shift?: boolean;
  /** Cmd on macOS, Ctrl elsewhere. */
  mod?: boolean;
  alt?: boolean;
};

export type Hotkey = {
  id: string;
  /** What the shortcut does, as the settings page says it. */
  label: string;
  description: string;
  combo: HotkeyCombo;
};

export const HOTKEYS = [
  {
    id: "new-chat",
    label: "New chat",
    description: "Start a new chat from anywhere in the app.",
    combo: { key: "n", shift: true },
  },
] as const satisfies readonly Hotkey[];

export type HotkeyId = (typeof HOTKEYS)[number]["id"];

export function getHotkey(id: HotkeyId): Hotkey {
  const hotkey = HOTKEYS.find((candidate) => candidate.id === id);
  if (!hotkey) {
    throw new Error(`Unknown hotkey "${id}".`);
  }
  return hotkey;
}

const isMac =
  typeof navigator !== "undefined" &&
  /Mac|iPhone|iPad/.test(navigator.platform);

/**
 * The key a keystroke names, spelled the way a combo spells it.
 *
 * `key` first, because it follows the layout: on Dvorak the letter N is not where QWERTY puts it, and
 * the key a person presses when told "N" is the one that writes an N. A layout that writes another
 * script has no such key. Shift and the N key write "Т" on Russian and "Ν" (Greek capital nu, not a
 * Latin N) on Greek, so a shortcut read from `key` alone never fired there. When `key` is a single
 * character outside ASCII, the physical key in `code` is the only N there is.
 */
export function keyOf(event: KeyboardEvent): string {
  const written = event.key.toLowerCase();
  if (written.length !== 1 || written.charCodeAt(0) < 0x80) return written;
  const physical = /^(?:Key|Digit)([A-Z0-9])$/.exec(event.code);
  return physical?.[1]?.toLowerCase() ?? written;
}

/**
 * Whether this keystroke is this combo — exactly, not at-least.
 *
 * Every modifier is compared, including the ones the combo does not ask for: Shift+N must not
 * fire on Cmd+Shift+N, or the combo would shadow whatever that means to the browser. `mod` is
 * Cmd on a Mac and Ctrl elsewhere, and the one it is not still has to be up.
 */
export function matchesHotkey(
  event: KeyboardEvent,
  combo: HotkeyCombo,
): boolean {
  const mod = isMac ? event.metaKey : event.ctrlKey;
  const otherMod = isMac ? event.ctrlKey : event.metaKey;
  return (
    keyOf(event) === combo.key &&
    event.shiftKey === Boolean(combo.shift) &&
    mod === Boolean(combo.mod) &&
    !otherMod &&
    event.altKey === Boolean(combo.alt)
  );
}

/**
 * The combo as a person's keyboard writes it, one part per key: symbols on a Mac (["⇧", "N"]),
 * names everywhere else (["Shift", "N"]). One entry per physical key so each can be drawn as
 * its own keycap.
 */
export function formatHotkey(combo: HotkeyCombo): string[] {
  const parts: string[] = [];
  if (combo.mod) parts.push(isMac ? "⌘" : "Ctrl");
  if (combo.alt) parts.push(isMac ? "⌥" : "Alt");
  if (combo.shift) parts.push(isMac ? "⇧" : "Shift");
  parts.push(combo.key.toUpperCase());
  return parts;
}