290 lines
12 KiB
TypeScript
290 lines
12 KiB
TypeScript
// SPDX-License-Identifier: GPL-3.0-or-later
|
|
// Copyright (C) 2026 ZiroEDA and contributors.
|
|
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
|
|
/**
|
|
* Stop the browser acting on a key this app has already bound.
|
|
*
|
|
* A desktop KiCad owns its accelerator table outright: `ACTIONS::open` takes
|
|
* Ctrl+O and nothing else in the process wants it. A tab does not. Chrome binds
|
|
* Ctrl+O to its own file picker, Ctrl+P to print, Ctrl+F and Ctrl+G to the find
|
|
* bar, Ctrl+D to bookmark, and unless the page says otherwise those run
|
|
* *alongside* whatever the page does - so pressing Ctrl+G in the project
|
|
* manager opened Chrome's find-next while the Gerber Viewer did or did not
|
|
* open, depending on whether anything here had bound it.
|
|
*
|
|
* `preventDefault()` on a keydown suppresses the browser's action for every
|
|
* shortcut it is willing to yield, which is most of them. This installs one
|
|
* capture-phase listener that does that for exactly the combos the app claims,
|
|
* and nothing else - a page that swallowed every Ctrl chord would break
|
|
* bookmarking, zooming and view-source for no reason.
|
|
*
|
|
* ## The ones no page can have
|
|
*
|
|
* A handful are reserved by the browser and cannot be intercepted from a normal
|
|
* tab at all: the keydown is either not delivered or `preventDefault()` is
|
|
* ignored on it. They are the ones that create or destroy browsing contexts -
|
|
* Ctrl+N, Ctrl+T, Ctrl+W and their Shift variants, Ctrl+Q, and the Ctrl+Tab
|
|
* pair. This is deliberate on the browser's part: a page that could swallow
|
|
* Ctrl+W could refuse to be closed.
|
|
*
|
|
* That matters here because **Ctrl+N is `ACTIONS::newProject`**. In a tab, both
|
|
* things happen: the New Project dialog opens and Chrome opens a new window.
|
|
* There is no page-side fix. {@link BROWSER_RESERVED} names them so the rest of
|
|
* the app can say so rather than appear broken, and so this module does not
|
|
* waste a `preventDefault()` that will be ignored.
|
|
*
|
|
* ## The one way to get them anyway
|
|
*
|
|
* The Keyboard Lock API (`navigator.keyboard.lock()`) does capture them, and is
|
|
* the mechanism browsers offer for exactly this case. It is Chromium-only and
|
|
* it only holds **while the document is fullscreen**, which is the trade: the
|
|
* app can have Ctrl+N and Ctrl+W when it is the whole screen and the user can
|
|
* always leave with Esc. {@link lockReservedKeys} engages it; nothing calls it
|
|
* automatically, because silently taking Ctrl+W from someone who did not ask is
|
|
* the behaviour the reservation exists to prevent.
|
|
*
|
|
* The two tables themselves - {@link BROWSER_RESERVED} and
|
|
* {@link BROWSER_REBINDS} - live in `browser_reserved.ts` and are re-exported
|
|
* here, because this module imports the schematic's `comboFromEvent` and a
|
|
* *declaration* site asking `browserSafeKey` what key to carry must not have to
|
|
* pull the dispatcher in behind it. See that file's note.
|
|
*/
|
|
import { markBrowserSuppressed, wasBrowserSuppressed } from '@ziroeda/wx/dom_events.js';
|
|
import { comboFromEvent, type KeyLike } from './hotkeys_basic_keys.js';
|
|
import { isBrowserReserved } from './browser_reserved.js';
|
|
|
|
export {
|
|
BROWSER_RESERVED,
|
|
BROWSER_REBINDS,
|
|
isBrowserReserved,
|
|
browserSafeKey,
|
|
} from './browser_reserved.js';
|
|
|
|
/**
|
|
* The bit of an event target that decides whether the user is typing into it.
|
|
*
|
|
* Structural rather than `HTMLElement` so the rule can be exercised without a
|
|
* DOM - this workspace's tests run in node, and a rule about which fields keep
|
|
* their keys is worth testing whether or not a browser is present.
|
|
*/
|
|
export interface FocusLike {
|
|
tagName?: string;
|
|
isContentEditable?: boolean;
|
|
type?: string;
|
|
}
|
|
|
|
/** Input types that are not somewhere you type, so a hotkey still works. */
|
|
const NON_TEXT_INPUTS = [
|
|
'checkbox',
|
|
'radio',
|
|
'button',
|
|
'submit',
|
|
'reset',
|
|
'range',
|
|
'color',
|
|
'file',
|
|
];
|
|
|
|
/**
|
|
* Whether the event is going to somewhere the user is typing.
|
|
*
|
|
* Ctrl+C, Ctrl+X, Ctrl+V, Ctrl+A and Ctrl+Z are all combos this app binds
|
|
* somewhere, and all of them are also how a text field works. Claiming them
|
|
* while a field has focus would break copying out of a project name box to fix
|
|
* a shortcut nobody pressed. This is the one place the port deliberately parts
|
|
* with wx, whose accelerator table fires regardless of focus - a browser user
|
|
* expects the field to win, and the project manager's own Edit menu greys out
|
|
* cut/copy/paste for exactly this reason.
|
|
*/
|
|
export function isTypingTarget(target: FocusLike | null | undefined): boolean {
|
|
if (!target) return false;
|
|
if (target.isContentEditable) return true;
|
|
const tag = target.tagName;
|
|
if (tag === 'TEXTAREA' || tag === 'SELECT') return true;
|
|
if (tag !== 'INPUT') return false;
|
|
return !NON_TEXT_INPUTS.includes(target.type ?? 'text');
|
|
}
|
|
|
|
/** Text workspaces above a CAD frame own their browser clipboard shortcuts.
|
|
* A selection in a non-focusable paragraph can leave the key target on body.
|
|
*/
|
|
export function nativeTextShortcutRegion(target: EventTarget | null): Element | null {
|
|
if (typeof document === 'undefined' || typeof Element === 'undefined') return null;
|
|
const selector = '[data-native-text-shortcuts="true"]';
|
|
const direct = target instanceof Element ? target.closest(selector) : null;
|
|
if (direct) return direct;
|
|
const selection = document.getSelection();
|
|
if (!selection || selection.isCollapsed || !selection.anchorNode || !selection.focusNode) return null;
|
|
const anchor = selection.anchorNode instanceof Element ? selection.anchorNode : selection.anchorNode.parentElement;
|
|
const focus = selection.focusNode instanceof Element ? selection.focusNode : selection.focusNode.parentElement;
|
|
const region = anchor?.closest(selector);
|
|
return region && focus && region.contains(focus) ? region : null;
|
|
}
|
|
|
|
export function isNativeTextShortcut(event: KeyboardEvent): boolean {
|
|
return (event.ctrlKey || event.metaKey) && !event.altKey &&
|
|
['a', 'c', 'v', 'x', 'y', 'z'].includes(event.key.toLowerCase()) &&
|
|
nativeTextShortcutRegion(event.target) !== null;
|
|
}
|
|
|
|
/** What the page took, and what it could not, for anything that wants to report it. */
|
|
export interface ClaimResult {
|
|
/** Combos this listener will suppress the browser's action for. */
|
|
claimed: string[];
|
|
/** Combos the app binds that the browser will not give up. */
|
|
reserved: string[];
|
|
}
|
|
|
|
/**
|
|
* Work out which of `combos` the page can take, without touching anything.
|
|
*
|
|
* Split from the listener so the rule is exercisable in a workspace whose
|
|
* tests run in node: what a page may claim is a fact about browsers, not about
|
|
* whether one happens to be running.
|
|
*/
|
|
export function planClaim(combos: Iterable<string>): ClaimResult & { lookup: ReadonlySet<string> } {
|
|
const claimed = new Set<string>();
|
|
const reserved: string[] = [];
|
|
|
|
for (const combo of combos) {
|
|
if (combo === '') continue;
|
|
// A gesture, not a keystroke - "Ctrl+Click", "Shift+Wheel", "Double-click".
|
|
if (/click|wheel|drag/i.test(combo)) continue;
|
|
if (isBrowserReserved(combo)) reserved.push(combo);
|
|
else claimed.add(combo.toLowerCase());
|
|
}
|
|
|
|
return { claimed: [...claimed], reserved: [...new Set(reserved)], lookup: claimed };
|
|
}
|
|
|
|
/**
|
|
* Suppress the browser's own action for each of `combos`.
|
|
*
|
|
* Capture phase, so the decision is made before any of the app's own handlers
|
|
* run and cannot be skipped by one of them calling `stopPropagation` first.
|
|
* Only `preventDefault` is called - the event still reaches the app, because
|
|
* this module's job is to stop the *browser*, not to dispatch anything.
|
|
*
|
|
* Returns the split of what it took, and a function to remove the listener.
|
|
* Safe to call with no `window`, where it plans and installs nothing.
|
|
*/
|
|
// The mark is the page's event plumbing (external/wx/dom_events.ts): wx's dialogs read it too.
|
|
export { wasBrowserSuppressed };
|
|
|
|
export function claimBrowserHotkeys(
|
|
combos: Iterable<string>,
|
|
): ClaimResult & { release: () => void } {
|
|
const plan = planClaim(combos);
|
|
|
|
if (typeof window === 'undefined') {
|
|
return { claimed: plan.claimed, reserved: plan.reserved, release: () => undefined };
|
|
}
|
|
|
|
const onKey = (e: KeyboardEvent): void => {
|
|
if (isNativeTextShortcut(e)) return;
|
|
if (isTypingTarget(e.target as FocusLike | null)) return;
|
|
if (!plan.lookup.has(comboFromEvent(e as unknown as KeyLike).toLowerCase())) return;
|
|
// Not stopPropagation: the app's handlers still need to see it.
|
|
//
|
|
// And record that *we* were the ones who suppressed it. This listener runs
|
|
// in the capture phase, so by the time a frame's dispatcher sees the event
|
|
// `defaultPrevented` is already true for every combo the app claims - which
|
|
// is every app hotkey. A dispatcher that reads `defaultPrevented` as "some
|
|
// other handler dealt with this" therefore stood down on all of them, and
|
|
// no accelerator fired anywhere in the app. The mark lets it tell our own
|
|
// browser-suppression apart from a real handler's.
|
|
markBrowserSuppressed(e);
|
|
e.preventDefault();
|
|
};
|
|
|
|
window.addEventListener('keydown', onKey, true);
|
|
|
|
return {
|
|
claimed: plan.claimed,
|
|
reserved: plan.reserved,
|
|
release: () => window.removeEventListener('keydown', onKey, true),
|
|
};
|
|
}
|
|
|
|
/** Whether this browser offers the Keyboard Lock API at all. */
|
|
export const keyboardLockAvailable = (): boolean =>
|
|
typeof navigator !== 'undefined' && 'keyboard' in navigator;
|
|
|
|
interface KeyboardLockAPI {
|
|
lock: (keyCodes?: string[]) => Promise<void>;
|
|
unlock: () => void;
|
|
}
|
|
|
|
const keyboardAPI = (): KeyboardLockAPI | undefined =>
|
|
(navigator as unknown as { keyboard?: KeyboardLockAPI }).keyboard;
|
|
|
|
/**
|
|
* Take the reserved combos, by going fullscreen and locking the keyboard.
|
|
*
|
|
* `navigator.keyboard.lock()` only holds while the document is fullscreen, so
|
|
* this requests fullscreen first; leaving fullscreen releases the lock on the
|
|
* browser's own initiative. Both steps need a user gesture, so call this from a
|
|
* click.
|
|
*
|
|
* Resolves to whether the lock is now held. `false` covers every failure the
|
|
* caller cannot do anything about - Firefox and Safari have no such API, and
|
|
* the fullscreen request can be refused - and none of them are errors worth
|
|
* throwing over.
|
|
*/
|
|
export async function lockReservedKeys(): Promise<boolean> {
|
|
const keyboard = keyboardAPI();
|
|
if (!keyboard) return false;
|
|
|
|
try {
|
|
if (!document.fullscreenElement) await document.documentElement.requestFullscreen();
|
|
// The codes, not the combos: lock() speaks KeyboardEvent.code.
|
|
await keyboard.lock(['KeyN', 'KeyT', 'KeyW', 'KeyQ', 'Tab']);
|
|
return true;
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
/** Give the reserved combos back. Leaving fullscreen does this anyway. */
|
|
export function unlockReservedKeys(): void {
|
|
keyboardAPI()?.unlock();
|
|
}
|
|
|
|
/**
|
|
* Hold the lock for as long as the app is fullscreen, however it got there.
|
|
*
|
|
* The lock is only permitted while the document is fullscreen, so the two
|
|
* states may as well be the same state: anything that puts the app fullscreen
|
|
* gets Ctrl+N and Ctrl+W with it, and leaving gives them straight back. That
|
|
* keeps the bargain the reservation exists to protect - the keys are only ever
|
|
* taken while the app fills the screen and Esc is the documented way out.
|
|
*
|
|
* Note this is the Fullscreen *API*, not the browser's own F11: pressing F11
|
|
* does not set `document.fullscreenElement`, so it does not engage this. The
|
|
* app has to ask.
|
|
*
|
|
* Returns a function that stops watching and releases.
|
|
*/
|
|
export function lockReservedKeysWhileFullscreen(): () => void {
|
|
if (typeof document === 'undefined' || !keyboardAPI()) return () => undefined;
|
|
|
|
const onChange = (): void => {
|
|
if (document.fullscreenElement) {
|
|
// lock() speaks KeyboardEvent.code, not our combo spelling.
|
|
void keyboardAPI()
|
|
?.lock(['KeyN', 'KeyT', 'KeyW', 'KeyQ', 'Tab'])
|
|
.catch(() => undefined);
|
|
} else {
|
|
unlockReservedKeys();
|
|
}
|
|
};
|
|
|
|
document.addEventListener('fullscreenchange', onChange);
|
|
onChange();
|
|
|
|
return () => {
|
|
document.removeEventListener('fullscreenchange', onChange);
|
|
unlockReservedKeys();
|
|
};
|
|
}
|