use-normalized-keys
Version:
A React hook with unified API and 60fps animations for normalized keyboard input handling, designed for productivity applications, drawing tools, and professional interfaces
119 lines • 4.15 kB
TypeScript
/**
* Platform-Specific Quirks and Edge Case Handling
*
* This module handles platform-specific keyboard input quirks and edge cases
* to ensure consistent behavior across different operating systems and browsers.
*
* Sources:
* - Windows Shift+Numpad: https://stackoverflow.com/questions/55339015/shift-key-released-when-pressing-numpad
* - macOS Meta key timeout: https://github.com/xyflow/xyflow/issues/4895
* - Focus loss recovery: https://forum.playcanvas.com/t/no-key-up-when-focus-lost-character-keeps-moving/14125
*/
export declare const Platform: {
isWindows: () => boolean;
isMacOS: () => boolean;
isLinuxPlatform: () => boolean;
isWindowsUA: () => boolean;
isMacOSUA: () => boolean;
isLinuxUA: () => boolean;
readonly isWin: boolean;
readonly isMac: boolean;
readonly isLinux: boolean;
};
type BufferedEvent = {
event: KeyboardEvent;
timestamp: number;
timeoutId: number | null;
};
type QuirkState = {
bufferedShiftUp: BufferedEvent | null;
numpadUpTime: number;
shiftIsDown: boolean;
emitEvent: ((event: KeyboardEvent) => void) | null;
recentEvents: Array<{
type: 'keydown' | 'keyup';
key: string;
code: string;
timestamp: number;
}>;
};
/**
* Interface for tracking platform-specific state
*/
interface PlatformQuirkState {
windowsShiftQuirks: QuirkState;
macOSMetaTimeoutId: number | null;
macOSMetaLastActivity: number;
}
/**
* Creates a new platform quirk state tracker
*/
export declare function createPlatformQuirkState(): PlatformQuirkState;
/**
* Sets up the event emission callback for buffered events
*
* @param quirkState - Platform quirk state tracker
* @param emitter - Function to call when events should be emitted
*/
export declare function setEventEmitter(quirkState: PlatformQuirkState, emitter: (event: KeyboardEvent) => void): void;
/**
* Processes keyboard events for Windows Shift+Numpad phantom suppression with proper buffering
*
* @param e - The keyboard event to check
* @param keyStates - Map of current key states (your internal tracker)
* @param quirkStateContainer - Platform quirk state tracker
* @param debug - Optional debug flag to enable logging (defaults to false)
* @returns 'emit' | 'buffer' | 'suppress' to indicate how to handle the event
*/
export declare function shouldSuppressWindowsShiftPhantom(e: KeyboardEvent, keyStates: Map<string, {
isDown: boolean;
}>, quirkStateContainer: PlatformQuirkState, debug?: boolean): 'emit' | 'buffer' | 'suppress';
/**
* Handles macOS Meta key timeout issues
*
* @param event - The keyboard event
* @param quirkState - Platform quirk state tracker
* @param onMetaTimeout - Callback to execute when Meta key times out
*/
export declare function handleMacOSMetaTimeout(event: KeyboardEvent, quirkState: PlatformQuirkState, onMetaTimeout: () => void): void;
/**
* Performs cross-platform consistency checks on key events
*
* @param event - The keyboard event to validate
* @param quirkState - Platform quirk state tracker
* @returns Object with validation results and any necessary corrections
*/
export declare function validateKeyEventConsistency(event: KeyboardEvent, quirkState: PlatformQuirkState): {
isValid: boolean;
corrections: string[];
warnings: string[];
};
/**
* Cleans up platform quirk state and timers
*
* @param quirkState - Platform quirk state tracker to clean up
*/
export declare function cleanupPlatformQuirks(quirkState: PlatformQuirkState): void;
/**
* Gets platform-specific debugging information
*
* @param quirkState - Platform quirk state tracker
* @returns Object with debugging information
*/
export declare function getPlatformDebugInfo(quirkState: PlatformQuirkState): {
platform: {
detected: string;
navigator: {
platform: string;
userAgent: string;
};
};
quirks: {
windowsShiftBuffered: boolean;
windowsShiftIsDown: boolean;
windowsRecentEvents: number;
macOSMetaTimeoutActive: boolean;
};
};
export {};
//# sourceMappingURL=platformQuirks.d.ts.map