keyboard-shortcuts-system

v1.0.0

Published

a year ago

A user-friendly keyboard shortcuts system for React applications

0High
0Medium
0Low

balaji_fabi

react keyboard shortcuts hotkeys accessibility

Keyboard Shortcuts System

A complete, user-friendly keyboard shortcuts system for React applications. This system allows users to:

Use predefined navigation shortcuts
Create custom shortcuts for any button in the application
Manage shortcuts through an elegant UI
Trigger button clicks via keyboard combinations

Features

Keyboard Shortcut Recording: Users can record keyboard shortcuts by pressing the actual key combinations instead of typing them
Function Key Support: Support for function keys (F1-F12) that work even when typing in form fields
Enhanced Visual Button Selection: The modal temporarily closes during button selection for an unobstructed view
Interactive Selection Experience: Buttons are highlighted when hovered over during selection mode
Seamless Workflow: The modal automatically reopens after button selection with all form data preserved
Persistent Storage: Shortcuts are saved to localStorage and persist across page refreshes
Customizable: Easily integrate with any React application
User-Friendly: Intuitive UI with clear visual feedback at every step
Flexible: Works with any button in your application
Guided Experience: Clear instructions and notifications guide users through the process

Installation

NPM Package

Install the package:

npm install keyboard-shortcuts-system
# or
yarn add keyboard-shortcuts-system

Install peer dependencies:

npm install antd @ant-design/icons
# or
yarn add antd @ant-design/icons

CDN Usage

You can use the F8 key handler directly from a CDN without installing the npm package:

Standalone F8 Handler

<!-- Using unpkg -->
<script src="https://unpkg.com/keyboard-shortcuts-system/dist/f8-handler.min.js"></script>

<!-- OR using jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/keyboard-shortcuts-system/dist/f8-handler.min.js"></script>

When using the CDN version, the F8 handler is available under the global F8Handler object:

<script>
  // Initialize the F8 handler with default options
  const cleanup = F8Handler.default();
  
  // Or with custom options
  const cleanupCustom = F8Handler.default({
    debug: true,                                // Enable console logging
    buttonSelector: '#my-submit-button',        // Custom button selector
    preventDefault: true                        // Prevent default F8 behavior
  });
  
  // Later, if you want to remove the handler
  cleanup();
</script>

Full React Component Library (requires React and Ant Design)

For the complete React component library, you need to include React and Ant Design first:

<!-- React dependencies -->
<script src="https://unpkg.com/react@17/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@17/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/antd/dist/antd.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/antd/dist/antd.min.css">

<!-- Then load the keyboard shortcuts library -->
<script src="https://unpkg.com/keyboard-shortcuts-system/dist/keyboard-shortcuts.min.js"></script>

Example: Using the F8 Handler in a Plain HTML Page

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>F8 Handler Demo</title>
    <style>
        button { padding: 10px 20px; background: #4CAF50; color: white; border: none; }
    </style>
</head>
<body>
    <h1>Press F8 to Submit</h1>
    <form>
        <input type="text" placeholder="Type something...">
        <button type="submit" id="submit-button">Submit</button>
    </form>
    
    <!-- Load the F8 handler from CDN -->
    <script src="https://unpkg.com/keyboard-shortcuts-system/dist/f8-handler.min.js"></script>
    <script>
        // Initialize the F8 handler
        const cleanup = F8Handler.default({
            debug: true,
            buttonSelector: '#submit-button'
        });
        
        // Log when the form is submitted
        document.querySelector('form').addEventListener('submit', function(e) {
            e.preventDefault();
            console.log('Form submitted!');
            alert('Form submitted!');
        });
    </script>
</body>
</html>

Usage

1. Wrap your application with the provider

import { KeyboardShortcutsProvider } from './keyboard-shortcuts-system/src';
import ShortcutHelpModal from './keyboard-shortcuts-system/src/components/ShortcutHelpModal';

// Define default keyboard shortcuts
const defaultShortcuts = [
  { 
    id: 'dashboard', 
    keys: 'Alt+D', 
    description: 'Go to Dashboard',
    action: { type: 'route', path: '/dashboard' }, 
    category: 'Navigation'
  },
  { 
    id: 'profile', 
    keys: 'Alt+P', 
    description: 'Go to Profile',
    action: { type: 'route', path: '/profile' }, 
    category: 'Navigation'
  },
  { 
    id: 'help', 
    keys: 'Alt+/', 
    description: 'Show Keyboard Shortcuts Help',
    action: { type: 'function', handler: () => {} }, 
    category: 'Help'
  }
];

function App() {
  return (
    <KeyboardShortcutsProvider globalShortcuts={defaultShortcuts}>
      <YourApp />
      <ShortcutHelpModal />
    </KeyboardShortcutsProvider>
  );
}

2. Add the ShortcutManager component to your UI

import { ShortcutManager } from './keyboard-shortcuts-system/src';

function Header() {
  return (
    <header>
      <h1>My App</h1>
      <ShortcutManager buttonText="Keyboard Shortcuts" />
    </header>
  );
}

3. Use the useKeyboardShortcuts hook in your components

import { useKeyboardShortcuts } from './keyboard-shortcuts-system/src';

function MyComponent() {
  const { registerShortcut, unregisterShortcut } = useKeyboardShortcuts();
  
  useEffect(() => {
    // Register a shortcut for a button
    registerShortcut(
      'save_form',
      'Alt+S',
      { 
        type: 'element', 
        selector: '#save-button', 
        event: 'click' 
      },
      { 
        description: 'Save Form',
        category: 'Forms'
      }
    );
    
    // Clean up when component unmounts
    return () => {
      unregisterShortcut('save_form');
    };
  }, [registerShortcut, unregisterShortcut]);
  
  return (
    <div>
      <button id="save-button" onClick={handleSave}>Save</button>
    </div>
  );
}

4. Add the ShortcutDemo component to demonstrate usage

import { ShortcutDemo } from './keyboard-shortcuts-system/src';

function Routes() {
  return (
    <Switch>
      <Route path="/shortcut-demo" component={ShortcutDemo} />
      {/* Other routes */}
    </Switch>
  );
}

API Reference

KeyboardShortcutsProvider

Props:

children: React nodes
globalShortcuts: Array of default shortcuts

useKeyboardShortcuts

Returns:

shortcuts: Array of all registered shortcuts
registerShortcut(id, keys, action, options): Function to register a new shortcut
unregisterShortcut(id): Function to remove a shortcut
showHelpModal: Boolean state of the help modal
setShowHelpModal: Function to show/hide the help modal

ShortcutManager