- {/* Master Navigation Column (Responsive) */}
-
-
setIsSidebarCollapsed(!isSidebarCollapsed)} />
-
+ return (
+
+ {/* Master Navigation Column (Responsive) */}
+
+
setIsSidebarCollapsed(!isSidebarCollapsed)}
+ />
+
- {/* Viewport Execution Layer */}
-
- {/* Global Command Header */}
-
setIsMobileNavOpen(!isMobileNavOpen)}
- isSidebarCollapsed={isSidebarCollapsed}
- onToggleSidebar={() => setIsSidebarCollapsed(!isSidebarCollapsed)}
- />
+ {/* Viewport Execution Layer */}
+
+ {/* Global Command Header */}
+
setIsMobileNavOpen(!isMobileNavOpen)}
+ isSidebarCollapsed={isSidebarCollapsed}
+ onToggleSidebar={() => setIsSidebarCollapsed(!isSidebarCollapsed)}
+ />
- {/* Operational Workspace */}
-
- {/* Centered Payload Container */}
-
-
-
-
-
+
+
+
+
- {/* Real-time System Notifications */}
-
+ {/* Real-time System Notifications */}
+
- {/* Mobile Nav Overlay (Emergency protocols) */}
- {isMobileNavOpen && (
-
setIsMobileNavOpen(false)}
- >
-
e.stopPropagation()}
- >
-
setIsMobileNavOpen(false)} />
-
-
- )}
+ {/* Keyboard Shortcuts Help Modal */}
+
setShowHelp(false)} isAdmin={true} />
+
+ {/* Mobile Nav Overlay (Emergency protocols) */}
+ {isMobileNavOpen && (
+ setIsMobileNavOpen(false)}
+ >
+
e.stopPropagation()}
+ >
+
setIsMobileNavOpen(false)} />
+
+ );
};
export default AdminLayout;
diff --git a/Frontend/src/components/shared/ShortcutsHelp.jsx b/Frontend/src/components/shared/ShortcutsHelp.jsx
new file mode 100644
index 000000000..718e6530f
--- /dev/null
+++ b/Frontend/src/components/shared/ShortcutsHelp.jsx
@@ -0,0 +1,181 @@
+/**
+ * Shortcuts Help Modal
+ * Displays available keyboard shortcuts in a styled overlay.
+ */
+
+import React, { useState, useEffect } from 'react';
+import { formatShortcut, getShortcutDescription } from '../../hooks/useKeyboardShortcuts';
+
+const ShortcutsHelp = ({ isOpen, onClose, shortcuts = {} }) => {
+ const [selectedCategory, setSelectedCategory] = useState('navigation');
+
+ useEffect(() => {
+ if (isOpen) {
+ document.body.style.overflow = 'hidden';
+ } else {
+ document.body.style.overflow = 'unset';
+ }
+ return () => {
+ document.body.style.overflow = 'unset';
+ };
+ }, [isOpen]);
+
+ useEffect(() => {
+ const handleEscape = (e) => {
+ if (e.key === 'Escape' && isOpen) {
+ onClose();
+ }
+ };
+ window.addEventListener('keydown', handleEscape);
+ return () => window.removeEventListener('keydown', handleEscape);
+ }, [isOpen, onClose]);
+
+ if (!isOpen) return null;
+
+ // Categorize shortcuts
+ const categories = {
+ navigation: {
+ title: 'Navigation',
+ icon: (
+
+ ),
+ shortcuts: ['g,d', 'g,t', 'g,n', 'g,p', 'g,h', 'g,u', 'g,s', 'g,a'],
+ },
+ actions: {
+ title: 'Quick Actions',
+ icon: (
+
+ ),
+ shortcuts: ['ctrl+f', 'ctrl+k', 'ctrl+/', '?', 'escape'],
+ },
+ };
+
+ // Filter shortcuts based on what's available
+ const getAvailableShortcuts = (categoryShortcuts) => {
+ return categoryShortcuts.filter(s => s in shortcuts);
+ };
+
+ return (
+
+ {/* Backdrop */}
+
+
+ {/* Modal */}
+
+ {/* Header */}
+
+
+
+
+
+
Keyboard Shortcuts
+
Navigate faster with keyboard shortcuts
+
+
+
+
+
+
+ {/* Content */}
+
+ {/* Category Tabs */}
+
+ {Object.entries(categories).map(([key, category]) => {
+ const available = getAvailableShortcuts(category.shortcuts);
+ if (available.length === 0) return null;
+
+ return (
+
+ );
+ })}
+
+
+ {/* Shortcuts List */}
+
+ {categories[selectedCategory]?.shortcuts.map(shortcut => {
+ if (!(shortcut in shortcuts)) return null;
+
+ const description = getShortcutDescription(shortcut);
+ const formatted = formatShortcut(shortcut);
+
+ return (
+
+
{description}
+
+ {formatted.split('').map((char, index) => (
+
+ {char}
+
+ ))}
+
+
+ );
+ })}
+
+
+ {/* Tips */}
+
+
💡 Tips
+
+ - • Press G then wait for a second, then press the next key
+ - • Shortcuts don't work when typing in input fields
+ - • Press Esc to close any modal
+
+
+
+
+ {/* Footer */}
+
+
+
+ Press Ctrl + / to toggle this help
+
+
+
+
+
+
+ );
+};
+
+export default ShortcutsHelp;
diff --git a/Frontend/src/hooks/keyboard_shortcuts_config.js b/Frontend/src/hooks/keyboard_shortcuts_config.js
new file mode 100644
index 000000000..808d0d348
--- /dev/null
+++ b/Frontend/src/hooks/keyboard_shortcuts_config.js
@@ -0,0 +1,105 @@
+const USER_NAVIGATION_SHORTCUTS = {
+ 'g,d': '/user/dashboard',
+ 'g,t': '/user/my-tickets',
+ 'g,n': '/user/create-ticket',
+ 'g,p': '/user/profile',
+ 'g,h': '/user/help',
+};
+
+const ADMIN_NAVIGATION_SHORTCUTS = {
+ 'g,d': '/admin/dashboard',
+ 'g,t': '/admin/tickets',
+ 'g,u': '/admin/users',
+ 'g,s': '/admin/settings',
+ 'g,p': '/admin/profile',
+ 'g,a': '/admin/analytics',
+};
+
+const QUICK_ACTION_SHORTCUTS = {
+ 'ctrl+f': 'search',
+ 'ctrl+k': 'search',
+ 'ctrl+/': 'shortcuts-help',
+ '?': 'shortcuts-help',
+ escape: 'close-modal',
+};
+
+export const SHORTCUTS_LEGEND = [
+ { combo: 'G + D', description: 'Go to Dashboard' },
+ { combo: 'G + T', description: 'Go to Tickets' },
+ { combo: 'Ctrl + F', description: 'Focus Search' },
+ { combo: 'Ctrl + /', description: 'Show Keyboard Shortcuts' },
+];
+
+export const SHORTCUT_GROUPS = [
+ {
+ group: 'Navigation',
+ shortcuts: [
+ { keys: ['G', 'D'], description: 'Go to Dashboard' },
+ { keys: ['G', 'T'], description: 'Go to Tickets' },
+ { keys: ['G', 'U'], description: 'Go to Users (admin)' },
+ { keys: ['G', 'S'], description: 'Go to Settings' },
+ { keys: ['G', 'P'], description: 'Go to Profile' },
+ { keys: ['G', 'A'], description: 'Go to Analytics (admin)' },
+ ],
+ },
+ {
+ group: 'Quick actions',
+ shortcuts: [
+ { keys: ['Ctrl', 'F'], description: 'Focus search' },
+ { keys: ['Ctrl', 'K'], description: 'Focus search' },
+ { keys: ['Ctrl', '/'], description: 'Show keyboard shortcuts' },
+ { keys: ['?'], description: 'Show keyboard shortcuts' },
+ { keys: ['Esc'], description: 'Close modal' },
+ ],
+ },
+];
+
+export const SHORTCUT_LIST = SHORTCUT_GROUPS;
+
+export const normalizeRole = (role) => {
+ if (role === 'admin' || role === true || role?.isAdmin) return 'admin';
+ return 'user';
+};
+
+export const createRoleAwareShortcuts = (role = 'user') => ({
+ ...(normalizeRole(role) === 'admin' ? ADMIN_NAVIGATION_SHORTCUTS : USER_NAVIGATION_SHORTCUTS),
+ ...QUICK_ACTION_SHORTCUTS,
+});
+
+export const normalizeShortcutKey = (key = '') => {
+ const normalized = String(key).toLowerCase();
+ if (normalized === 'esc') return 'escape';
+ return normalized;
+};
+
+export const getShortcutAction = (shortcuts, keys) => {
+ const combo = keys.map(normalizeShortcutKey).join('+').replace('g+', 'g,');
+ return shortcuts[combo] || null;
+};
+
+export const isShortcutTypingTarget = (target) => {
+ if (!target) return false;
+
+ const tagName = target.tagName?.toUpperCase();
+ return (
+ tagName === 'INPUT' ||
+ tagName === 'TEXTAREA' ||
+ tagName === 'SELECT' ||
+ target.isContentEditable === true
+ );
+};
+
+export const getShortcutDescription = (shortcut) => {
+ const normalizedShortcut = String(shortcut).toLowerCase();
+ const match = SHORTCUT_GROUPS
+ .flatMap((group) => group.shortcuts)
+ .find(
+ (entry) =>
+ entry.keys
+ .map(normalizeShortcutKey)
+ .join('+')
+ .replace('g+', 'g,') === normalizedShortcut
+ );
+
+ return match?.description || shortcut;
+};
diff --git a/Frontend/src/hooks/keyboard_shortcuts_hook.test.jsx b/Frontend/src/hooks/keyboard_shortcuts_hook.test.jsx
new file mode 100644
index 000000000..f0098ba22
--- /dev/null
+++ b/Frontend/src/hooks/keyboard_shortcuts_hook.test.jsx
@@ -0,0 +1,18 @@
+import { fireEvent, renderHook } from '@testing-library/react';
+import useKeyboardShortcuts from './useKeyboardShortcuts';
+import { mockedNavigate } from '../../jest.setup';
+
+describe('useKeyboardShortcuts', () => {
+ beforeEach(() => {
+ mockedNavigate.mockClear();
+ });
+
+ test('keeps G navigation sequence active when callers pass inline empty custom shortcuts', () => {
+ renderHook(() => useKeyboardShortcuts({}, { role: 'admin' }));
+
+ fireEvent.keyDown(window, { key: 'g' });
+ fireEvent.keyDown(window, { key: 'd' });
+
+ expect(mockedNavigate).toHaveBeenCalledWith('/admin/dashboard');
+ });
+});
diff --git a/Frontend/src/hooks/useKeyboardShortcuts.js b/Frontend/src/hooks/useKeyboardShortcuts.js
new file mode 100644
index 000000000..f4a6b2627
--- /dev/null
+++ b/Frontend/src/hooks/useKeyboardShortcuts.js
@@ -0,0 +1,241 @@
+/**
+ * Keyboard Shortcuts Hook
+ * Provides global keyboard shortcuts for rapid navigation.
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import {
+ createRoleAwareShortcuts,
+ getShortcutDescription,
+ getShortcutAction,
+ isShortcutTypingTarget,
+ SHORTCUTS_LEGEND,
+ SHORTCUT_GROUPS,
+ SHORTCUT_LIST,
+} from './keyboard_shortcuts_config';
+
+const SEQUENCE_TIMEOUT_MS = 1000;
+const SEARCH_SELECTOR = [
+ '[data-shortcut-search]',
+ 'input[type="search"]',
+ 'input[placeholder*="Search" i]',
+ 'input[aria-label*="Search" i]',
+].join(',');
+
+const focusSearchField = () => {
+ const searchInput = document.querySelector(SEARCH_SELECTOR);
+ if (searchInput && typeof searchInput.focus === 'function') {
+ searchInput.focus();
+ return true;
+ }
+ return false;
+};
+
+const closeOpenModal = () => {
+ const closeButton = document.querySelector(
+ '[data-modal-close], [aria-label="Close shortcuts help"], [aria-label="Close keyboard shortcuts"], [aria-label="Close shortcuts legend"]'
+ );
+
+ if (closeButton && typeof closeButton.click === 'function') {
+ closeButton.click();
+ return true;
+ }
+
+ return false;
+};
+
+/**
+ * Hook to register keyboard shortcuts.
+ *
+ * @param {Object} customShortcuts - Additional shortcuts to merge with defaults.
+ * @param {Object} options - Configuration options.
+ * @param {boolean|string|Object} options.role - Current role; admin receives admin routes.
+ * @param {boolean} options.enabled - Whether shortcuts are enabled.
+ * @param {Function} options.onSearch - Callback for search shortcut.
+ * @param {Function} options.onShortcutsHelp - Callback for shortcuts help.
+ */
+export const useKeyboardShortcuts = (customShortcuts = {}, options = {}) => {
+ const normalizedOptions = customShortcuts?.isAdmin
+ ? { ...options, role: 'admin' }
+ : options;
+ const normalizedCustomShortcuts = customShortcuts?.isAdmin ? {} : customShortcuts;
+
+ const {
+ enabled = true,
+ role = 'user',
+ onSearch = null,
+ onShortcutsHelp = null,
+ } = normalizedOptions;
+
+ const navigate = useNavigate();
+ const [pendingKey, setPendingKey] = useState(null);
+ const [showHelp, setShowHelp] = useState(false);
+ const timeoutRef = useRef(null);
+ const pendingKeyRef = useRef(null);
+ const customShortcutsKey = JSON.stringify(normalizedCustomShortcuts || {});
+
+ const shortcuts = useMemo(
+ () => ({
+ ...createRoleAwareShortcuts(role),
+ ...(normalizedCustomShortcuts || {}),
+ }),
+ [role, customShortcutsKey]
+ );
+
+ const clearPendingKey = () => {
+ pendingKeyRef.current = null;
+ setPendingKey(null);
+ if (timeoutRef.current) {
+ clearTimeout(timeoutRef.current);
+ timeoutRef.current = null;
+ }
+ };
+
+ useEffect(() => {
+ if (!enabled) return undefined;
+
+ const handleAction = (action) => {
+ if (!action) return;
+
+ if (action === 'search') {
+ if (onSearch) {
+ onSearch();
+ } else {
+ focusSearchField();
+ }
+ return;
+ }
+
+ if (action === 'shortcuts-help') {
+ if (onShortcutsHelp) {
+ onShortcutsHelp();
+ } else {
+ setShowHelp(true);
+ }
+ return;
+ }
+
+ if (action === 'close-modal') {
+ setShowHelp(false);
+ closeOpenModal();
+ return;
+ }
+
+ navigate(action);
+ };
+
+ const handleKeyDown = (event) => {
+ if (isShortcutTypingTarget(event.target)) return;
+
+ const key = event.key.toLowerCase();
+ const isCtrl = event.ctrlKey || event.metaKey;
+ const isAlt = event.altKey;
+ const isShift = event.shiftKey;
+
+ if (key === 'escape') {
+ event.preventDefault();
+ handleAction(shortcuts.escape);
+ clearPendingKey();
+ return;
+ }
+
+ if (isCtrl && key === 'f') {
+ event.preventDefault();
+ handleAction(getShortcutAction(shortcuts, ['ctrl', 'f']));
+ clearPendingKey();
+ return;
+ }
+
+ if (isCtrl && key === 'k') {
+ event.preventDefault();
+ handleAction(getShortcutAction(shortcuts, ['ctrl', 'k']));
+ clearPendingKey();
+ return;
+ }
+
+ if (isCtrl && key === '/') {
+ event.preventDefault();
+ handleAction(getShortcutAction(shortcuts, ['ctrl', '/']));
+ clearPendingKey();
+ return;
+ }
+
+ if (!isCtrl && !isAlt && key === '?') {
+ event.preventDefault();
+ handleAction(getShortcutAction(shortcuts, ['?']));
+ clearPendingKey();
+ return;
+ }
+
+ if (pendingKeyRef.current === 'g') {
+ const action = getShortcutAction(shortcuts, ['g', key]);
+ if (action) {
+ event.preventDefault();
+ handleAction(action);
+ }
+ clearPendingKey();
+ return;
+ }
+
+ if (!isCtrl && !isAlt && !isShift && key === 'g') {
+ event.preventDefault();
+ pendingKeyRef.current = 'g';
+ setPendingKey('g');
+ timeoutRef.current = setTimeout(clearPendingKey, SEQUENCE_TIMEOUT_MS);
+ }
+ };
+
+ window.addEventListener('keydown', handleKeyDown);
+ return () => {
+ window.removeEventListener('keydown', handleKeyDown);
+ clearPendingKey();
+ };
+ }, [enabled, navigate, onSearch, onShortcutsHelp, shortcuts]);
+
+ return {
+ shortcuts,
+ pendingKey,
+ showHelp,
+ setShowHelp,
+ };
+};
+
+/**
+ * Get shortcut display string.
+ * @param {string} shortcut - Shortcut key combination.
+ * @returns {string} - Formatted string for display.
+ */
+export const formatShortcut = (shortcut) => {
+ const isMac = navigator.platform.toUpperCase().indexOf('MAC') >= 0;
+
+ return shortcut
+ .split('+')
+ .map((key) => {
+ switch (key.toLowerCase()) {
+ case 'ctrl':
+ return isMac ? '⌘' : 'Ctrl';
+ case 'shift':
+ return isMac ? '⇧' : 'Shift';
+ case 'alt':
+ return isMac ? '⌥' : 'Alt';
+ case 'g':
+ return 'G';
+ default:
+ return key.toUpperCase();
+ }
+ })
+ .join(isMac ? '' : '+');
+};
+
+export {
+ getShortcutDescription,
+ SHORTCUTS_LEGEND,
+ SHORTCUT_GROUPS,
+ SHORTCUT_LIST,
+ createRoleAwareShortcuts,
+ getShortcutAction,
+ isShortcutTypingTarget,
+};
+
+export default useKeyboardShortcuts;
diff --git a/Frontend/tests/keyboard_shortcuts.test.js b/Frontend/tests/keyboard_shortcuts.test.js
new file mode 100644
index 000000000..ce02fcaf8
--- /dev/null
+++ b/Frontend/tests/keyboard_shortcuts.test.js
@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import {
+ createRoleAwareShortcuts,
+ getShortcutAction,
+ getShortcutDescription,
+ isShortcutTypingTarget,
+ SHORTCUTS_LEGEND,
+} from '../src/hooks/keyboard_shortcuts_config.js';
+
+test('maps admin dashboard and tickets shortcuts to admin routes', () => {
+ const shortcuts = createRoleAwareShortcuts('admin');
+
+ assert.equal(getShortcutAction(shortcuts, ['g', 'd']), '/admin/dashboard');
+ assert.equal(getShortcutAction(shortcuts, ['g', 't']), '/admin/tickets');
+});
+
+test('maps user dashboard and tickets shortcuts to user routes', () => {
+ const shortcuts = createRoleAwareShortcuts('user');
+
+ assert.equal(getShortcutAction(shortcuts, ['g', 'd']), '/user/dashboard');
+ assert.equal(getShortcutAction(shortcuts, ['g', 't']), '/user/my-tickets');
+});
+
+test('keeps browser-safe quick actions available', () => {
+ const shortcuts = createRoleAwareShortcuts('admin');
+
+ assert.equal(getShortcutAction(shortcuts, ['ctrl', 'f']), 'search');
+ assert.equal(getShortcutAction(shortcuts, ['ctrl', 'k']), 'search');
+ assert.equal(getShortcutAction(shortcuts, ['ctrl', '/']), 'shortcuts-help');
+ assert.equal(getShortcutAction(shortcuts, ['?']), 'shortcuts-help');
+});
+
+test('does not run global shortcuts while users are typing', () => {
+ assert.equal(isShortcutTypingTarget({ tagName: 'INPUT' }), true);
+ assert.equal(isShortcutTypingTarget({ tagName: 'TEXTAREA' }), true);
+ assert.equal(isShortcutTypingTarget({ tagName: 'DIV', isContentEditable: true }), true);
+ assert.equal(isShortcutTypingTarget({ tagName: 'BUTTON' }), false);
+});
+
+test('legend documents required dashboard, tickets, search, and help shortcuts', () => {
+ const combos = SHORTCUTS_LEGEND.map(({ combo }) => combo);
+
+ assert.deepEqual(combos, ['G + D', 'G + T', 'Ctrl + F', 'Ctrl + /']);
+});
+
+test('normalizes role objects and boolean admin flags', () => {
+ assert.equal(createRoleAwareShortcuts({ isAdmin: true })['g,u'], '/admin/users');
+ assert.equal(createRoleAwareShortcuts(true)['g,s'], '/admin/settings');
+ assert.equal(createRoleAwareShortcuts({ isAdmin: false })['g,n'], '/user/create-ticket');
+});
+
+test('describes normalized escape shortcut consistently', () => {
+ assert.equal(getShortcutDescription('escape'), 'Close modal');
+});