Files
Tom Moor 8fb8f4d3d4 feat: Alt+Up/Down moves to the previous/next document in the sidebar (#14034)
* feat: Alt+Up/Down moves to the previous/next document in the sidebar

* feat: Sidebar keyboard navigation works across collections and root rows
2026-10-11 15:33:19 -04:00

164 lines
5.1 KiB
TypeScript

import { useContext, useEffect } from "react";
import { isModKey } from "@shared/utils/keyboard";
import { SplitViewContext } from "~/components/SplitView/context";
import {
isKeyboardWidget,
isWithinKeyboardWidget,
} from "~/utils/isKeyboardWidget";
import { getFocusedSplitPane } from "~/utils/splitView";
type Callback = (event: KeyboardEvent) => void;
export type KeyFilter = ((event: KeyboardEvent) => boolean) | string;
export type Options = {
/**
* Fire even when focus is inside a control that handles its own keyboard
* input, such as a text input, menu, or dialog.
*/
allowInInput?: boolean;
/**
* Fire when focus is inside a text input, such as the editor, but not inside
* a widget such as a menu or dialog. Keys that the input already handled are
* ignored.
*/
allowInTextInput?: boolean;
/** Require the platform modifier key (Cmd on macOS, Ctrl elsewhere) to be held. */
metaKey?: boolean;
/** Require the Alt/Option key to be held. */
altKey?: boolean;
/** Require the Shift key to be held. */
shiftKey?: boolean;
};
type RegisteredCallback = {
callback: Callback;
options?: Options;
};
// Registered keyboard event callbacks
let callbacks: RegisteredCallback[] = [];
// Track if IME input suggestions are open so we can ignore keydown shortcuts
// in this case, they should never be triggered from mobile keyboards.
let imeOpen = false;
// Returns true when the event's modifier keys satisfy the given options.
const matchesModifiers = (event: KeyboardEvent, options?: Options) => {
if (options?.metaKey ? !isModKey(event) : isModKey(event)) {
return false;
}
if (options?.altKey && !event.altKey) {
return false;
}
if (options?.shiftKey && !event.shiftKey) {
return false;
}
return true;
};
// Based on implementation in react-use
// https://github.com/streamich/react-use/blob/master/src/useKey.ts#L15-L22
// A string filter matches the bare key with the modifiers described by options;
// use a function filter for anything the options cannot express.
const createKeyPredicate = (keyFilter: KeyFilter, options?: Options) =>
typeof keyFilter === "function"
? keyFilter
: typeof keyFilter === "string"
? (event: KeyboardEvent) => {
// Synthetic events may be dispatched without a key.
if (!event.key) {
return false;
}
// Match case-insensitively only when Shift is required, since a
// shifted letter reports an uppercase event.key (e.g. Cmd+Shift+P).
// Otherwise match exactly so a bare shortcut does not fire when Shift
// is held (e.g. "n" must not trigger on Shift+N).
const keyMatches = options?.shiftKey
? event.key.toLowerCase() === keyFilter.toLowerCase()
: event.key === keyFilter;
return keyMatches && matchesModifiers(event, options);
}
: keyFilter
? (_event: KeyboardEvent) => true
: (_event: KeyboardEvent) => false;
/**
* Registers a global keyboard shortcut for the lifetime of the component.
*
* @param key The key to match, either a string for a single key or a predicate
* function for full control over the event.
* @param fn The callback to invoke when the shortcut matches.
* @param options Behavioral options, including the required modifier keys.
*/
export default function useKeyDown(
key: KeyFilter,
fn: Callback,
options?: Options
): void {
const { pane, isSplitView } = useContext(SplitViewContext);
const predicate = createKeyPredicate(key, options);
useEffect(() => {
const handler = (event: KeyboardEvent) => {
// Shortcuts registered within an unfocused split view pane are ignored
// so that only the focused pane responds to them.
if (isSplitView && pane !== getFocusedSplitPane()) {
return;
}
if (predicate(event)) {
fn(event);
}
};
callbacks.push({
callback: handler,
options,
});
return () => {
callbacks = callbacks.filter((cb) => cb.callback !== handler);
};
}, [fn, predicate, options, isSplitView, pane]);
}
window.addEventListener("keydown", (event) => {
if (imeOpen) {
return;
}
// Track whether defaultPrevented was already set by an external handler (e.g.
// Radix UI's DismissableLayer) so we only break on preventDefault calls made
// by our own callbacks.
const wasDefaultPrevented = event.defaultPrevented;
const isWidget = isKeyboardWidget(event.target);
const allowsTextInput =
!wasDefaultPrevented && !isWithinKeyboardWidget(event.target);
// reverse so that the last registered callbacks get executed first
for (const registered of [...callbacks].reverse()) {
if (!wasDefaultPrevented && event.defaultPrevented) {
break;
}
if (
!isWidget ||
registered.options?.allowInInput ||
(registered.options?.allowInTextInput && allowsTextInput) ||
isModKey(event)
) {
registered.callback(event);
}
}
});
window.addEventListener("compositionstart", () => {
imeOpen = true;
});
window.addEventListener("compositionend", () => {
imeOpen = false;
});