Lutra/ui/src/components/terminal/keys.ts
danny a8daf269fb M3.6: integrated terminal with PTY sessions and xterm.js sub-tabs
- crates/terminal: portable-pty sessions (ConPTY on Windows) with reader,
  writer and waiter threads, UTF-8 chunking, a 1 MiB output buffer with
  backpressure, a non-blocking input queue, resize, kill and exit codes;
  default shell pwsh -> powershell -> cmd on Windows, $SHELL or /bin/sh.
- Engine: terminal.create/input/resize/close, terminalOutput (capped per
  terminal and per pump, round-robin) and terminalExited through the pump;
  terminals close with the project and on app.quit.
- UI: Terminal tab in the bottom panel (tabs next to Find), xterm.js with
  the fit addon, sub-tabs, copy/paste, a focus rule that leaves plain Ctrl
  keys to the shell, terminal.open (Mod+Shift+T), --lt-terminal-* ANSI
  tokens in both themes (text colours AA) and a 4.5:1 minimum contrast.
- Tests: real-shell crate tests (UTF-8, backpressure), engine and TCP
  control tests, Vitest with a mocked xterm; live check on port 7936;
  docs and parity rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 21:10:37 +02:00

79 lines
2.6 KiB
TypeScript

/**
* Keyboard rules of the integrated terminal (M3.6).
*
* **Focus and shortcut rule:** while a terminal has the focus, keys belong
* to the shell. A Lutra shortcut still reaches Lutra when it uses Mod
* together with Shift or Alt (`Mod+Shift+P` palette, `Mod+Alt+F` Find,
* `Mod+Shift+T` terminal…), or on macOS any Cmd shortcut, since shells get
* no Cmd keys. Plain `Ctrl+<key>` and single keys go to the shell, so
* `Ctrl+C`, `Ctrl+W`, `Ctrl+P`, `Ctrl+R`, `Ctrl+1`… keep their shell
* meaning.
*
* **Copy and paste:** `Mod+Shift+C` copies the selection, `Mod+Shift+V`
* pastes. On Windows and Linux `Ctrl+C` copies when text is selected (and
* otherwise interrupts, as the shell expects) and `Ctrl+V` pastes; on macOS
* `Cmd+C` and `Cmd+V` do.
*/
/** Attribute on the element that holds a terminal. */
export const TERMINAL_ATTRIBUTE = "data-lt-terminal";
/**
* Whether the focus of a key event is inside a terminal.
*
* @param event - the key event.
* @returns true when its target lies in an element with
* {@link TERMINAL_ATTRIBUTE}.
*/
export function inTerminal(event: KeyboardEvent): boolean {
const target = event.target;
return target instanceof Element && target.closest(`[${TERMINAL_ATTRIBUTE}]`) !== null;
}
/**
* Whether a key event that matches a Lutra shortcut should run it, given
* the focus rule above.
*
* @param event - the key event.
* @param mac - whether Lutra runs on macOS.
* @returns false when a terminal has the focus and the shell should get
* the key.
*/
export function shortcutReachesLutra(event: KeyboardEvent, mac: boolean): boolean {
if (!inTerminal(event)) {
return true;
}
if (mac) {
return event.metaKey;
}
return event.ctrlKey && (event.shiftKey || event.altKey);
}
/** What a key in the terminal does with the clipboard. */
export type ClipboardAction = "copy" | "paste" | null;
/**
* The clipboard action of a key event in the terminal.
*
* @param event - the keydown event.
* @param hasSelection - whether the terminal has selected text.
* @param mac - whether Lutra runs on macOS.
* @returns the action, or null when the key goes to the shell.
*/
export function clipboardAction(event: KeyboardEvent, hasSelection: boolean, mac: boolean): ClipboardAction {
if (event.type !== "keydown" || event.altKey) {
return null;
}
const key = event.code;
const mod = mac ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey;
if (!mod) {
return null;
}
if (key === "KeyC" && (event.shiftKey || hasSelection || mac)) {
return "copy";
}
if (key === "KeyV") {
return "paste";
}
return null;
}