@keybindy/react
Version:
Keybindy for React: Simple, scoped keyboard shortcuts that require little setup. designed to smoothly blend in with your React applications, allowing for robust keybinding functionality without the overhead.
171 lines (165 loc) • 6.05 kB
TypeScript
import React from 'react';
import ShortcutManager, { Keys, ShortcutHandler, ShortcutOptions, Shortcut } from '@keybindy/core';
export { Keys, Shortcut, ShortcutOptions } from '@keybindy/core';
import * as react_jsx_runtime from 'react/jsx-runtime';
/**
* Represents a shortcut definition for the `<Keybindy />` component.
*/
type KeybindyShortcut = {
/**
* The key combination(s) to listen for.
* Can be a single array of keys or an array of key combinations.
*/
keys: Keys[] | Keys[][];
/**
* Callback function to invoke when the shortcut is triggered.
*/
handler: ShortcutHandler;
/**
* Optional configuration, including scope and other metadata.
*/
options?: Omit<ShortcutOptions, 'scope'>;
};
/**
* Props for the `<Keybindy />` component.
*/
type KeybindyProps = {
/**
* The scope under which the shortcuts should be active.
* This allows managing different contexts for shortcuts.
*/
scope?: 'global' | string;
/**
* Array of shortcut definitions to register for this scope.
*/
shortcuts?: KeybindyShortcut[];
/**
* Whether the shortcuts should be disabled for this scope.
* Defaults to `false`.
*/
disabled?: boolean;
/**
* Callback function that will be called when a shortcut is fired.
* Receives the fired shortcut info as an argument.
*/
onShortcutFired?: (info: Shortcut) => void;
/**
* Whether to enable debug logs in the console.
*/
logs?: boolean;
/**
* The content that will be rendered inside the Shortcut component.
*/
children?: React.ReactNode;
};
declare const Keybindy: React.NamedExoticComponent<KeybindyProps>;
type AllowedKeys = Omit<Keys, 'Ctrl (Left)' | 'Ctrl (Right)' | 'Shift (Left)' | 'Shift (Right)' | 'Alt (Left)' | 'Alt (Right)' | 'Meta (Left)' | 'Meta (Right)'>;
interface ShortcutLabelProps extends React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> {
/**
* Array of keys to display. Can be a single binding `['Ctrl', 'S']` or multiple bindings `[['Ctrl', 'S'], ['Cmd', 'S']]`.
*/
keys: AllowedKeys[] | AllowedKeys[][];
/**
* Custom render function for full control over how your keys are rendered.
* This function receives the entire `keys` array (either `string[]` or `string[][]`)
* and should return the ReactNode to be displayed.
*/
render?: (keys: AllowedKeys[] | AllowedKeys[][]) => React.ReactNode;
}
/**
* ... (rest of the description) ...
*
* @example
* // Default usage
* <ShortcutLabel keys={['ctrl', 's']} />
*
* @example
* // With multiple bindings
* <ShortcutLabel keys={[['ctrl', 's'], ['meta', 's']]} />
*
* @example
* // With custom render prop
* <ShortcutLabel
* keys={['ctrl', 'shift', 'a']}
* render={(keys) => {
* // 'keys' here will be ['ctrl', 'shift', 'a']
* return keys.map((key) => (
* <span key={key} style={{ color: '#00eaff' }}>
* {key.toUpperCase()}
* </span>
* ));
* }}
* />
*
* @example
* // With custom render prop for multiple bindings
* <ShortcutLabel
* keys={[['ctrl', 's'], ['meta', 's']]}
* render={(bindings) => {
* // 'bindings' here will be [['ctrl', 's'], ['meta', 's']]
* return bindings.map((binding, bindingIndex) => (
* <React.Fragment key={bindingIndex}>
* {binding.map((key, keyIndex) => (
* <span key={keyIndex} style={{ fontWeight: 'bold' }}>
* {key}
* </span>
* ))}
* {bindingIndex < bindings.length - 1 && ' or '}
* </React.Fragment>
* ));
* }}
* />
*
* @param {ShortcutLabelProps} props - Props for the ShortcutLabel component
* @param {string[] | string[][]} props.keys - The list of keys to display.
* @param {Function} [props.render] - Optional custom render function for full control over how your keys are rendered.
*
* @returns {JSX.Element} Rendered shortcut label
*/
declare const ShortcutLabel: ({ keys, render, style, ...props }: ShortcutLabelProps) => react_jsx_runtime.JSX.Element;
type UseKeybindyReturn = {
register: (keys: Keys[] | Keys[][], handler: ShortcutHandler, options?: ShortcutOptions) => void;
unregister: (keys: Keys[], scope?: string) => void;
enable: (keys: Keys[], scope?: string) => void;
disable: (keys: Keys[], scope?: string) => void;
toggle: (keys: Keys[], scope?: string) => void;
setScope: (scope: string) => void;
getCheatSheet: (scope?: string) => ({
keys: Keys[] | Keys[][];
hold: boolean;
sequential: boolean;
enabled: boolean;
} & Record<string, any>)[] | undefined;
destroy: () => void;
getScopeInfo: (scope?: string) => any;
getActiveScope: () => string | undefined;
popScope: () => void;
pushScope: (scope: string) => void;
resetScope: () => void;
getScopes: () => string[] | undefined;
isScopeActive: (scope: string) => boolean | undefined;
onTyping: (callback: (payload: {
key: string;
event: KeyboardEvent;
}) => void) => void;
enableAll: (scope?: string) => void;
clear: () => void;
disableAll: (scope?: string) => void;
manager: ShortcutManager | null;
};
/**
* React hook to manage keyboard shortcuts using a shared instance of `ShortcutManager`.
* This hook is safe for server-side rendering (SSR) and will only initialize the manager on the client.
*
* @param {Object} config - Configuration object.
* @param {boolean} [config.logs=false] - Whether to enable debug logs in the console.
* @param {(info: Shortcut) => void} [config.onShortcutFired] - Callback for when a shortcut is fired.
*
* @returns {Object} Object containing shortcut management methods and the manager instance (null on server).
*/
declare const useKeybindy: ({ logs, onShortcutFired, }?: {
logs?: boolean;
onShortcutFired?: (info: Shortcut) => void;
}) => UseKeybindyReturn;
export { Keybindy, ShortcutLabel, useKeybindy };
export type { KeybindyShortcut };