Merge pull request #527 from easyops-cn/copilot/fix-0fb12dbc-763e-4e6c-99eb-f49ee2f14f74

feat: Add configurable keyboard shortcut for search bar focus

closes #516

Author: weareoutman

README.md

@@ -59,6 +59,10 @@ module.exports = {
         // For Docs using Chinese, it is recomended to set:
         // language: ["en", "zh"],
 
+        // Customize the keyboard shortcut to focus search bar (default is "mod+k"):
+        // searchBarShortcutKeymap: "s", // Use 'S' key
+        // searchBarShortcutKeymap: "ctrl+shift+f", // Use Ctrl+Shift+F
+
         // If you're using `noIndex: true`, set `forceIgnoreNoIndex` to enable local index:
         // forceIgnoreNoIndex: true,
       }),
@@ -92,6 +96,7 @@ module.exports = {
 | ignoreCssSelectors                | string \| string[]                                                          | `[]`      | A list of css selectors to ignore when indexing each page.                                                                                                                                                                                                                                                                                                  |
 | searchBarShortcut                 | boolean                                                                     | `true`    | Whether to enable keyboard shortcut to focus in search bar.                                                                                                                                                                                                                                                                                                 |
 | searchBarShortcutHint             | boolean                                                                     | `true`    | Whether to show keyboard shortcut hint in search bar. Disable it if you need to hide the hint while shortcut is still enabled.                                                                                                                                                                                                                              |
+| searchBarShortcutKeymap           | string                                                                      | `"mod+k"` | Custom keyboard shortcut to focus the search bar. Supports formats like: `"s"` for single key, `"ctrl+k"` for key combinations, `"mod+k"` for Command+K (Mac) / Ctrl+K (others) - recommended cross-platform option, `"ctrl+shift+k"` for multiple modifiers.                                                                                            |
 | searchBarPosition                 | `"auto"` \| `"left"` \| `"right"`                                           | `"auto"`  | The side of the navbar the search bar should appear on. By default, it will try to autodetect based on your docusaurus config according to [the docs](https://docusaurus.io/docs/api/themes/configuration#navbar-search).                                                                                                                                   |
 | docsPluginIdForPreferredVersion   | string                                                                      |           | When you're using multi-instance of docs, set the docs plugin id which you'd like to check the preferred version with, for the search index.                                                                                                                                                                                                                |
 | zhUserDict                        | string                                                                      |           | Provide your custom dict for language of zh, [see here](https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8)                                                                                                                                                                                                                                |

docusaurus-search-local/src/client/theme/SearchBar/SearchBar.tsx

@@ -24,6 +24,7 @@ import {
   Mark,
   searchBarShortcut,
   searchBarShortcutHint,
+  searchBarShortcutKeymap,
   searchBarPosition,
   docsPluginIdForPreferredVersion,
   indexDocs,
@@ -34,6 +35,8 @@ import {
 import LoadingRing from "../LoadingRing/LoadingRing";
 import { normalizeContextByPath } from "../../utils/normalizeContextByPath";
 import { searchResultLimits } from "../../utils/proxiedGeneratedConstants";
+import { parseKeymap, matchesKeymap, getKeymapHints } from "../../utils/keymap";
+import { isMacPlatform } from "../../utils/platform";
 
 import styles from "./SearchBar.module.css";
 
@@ -387,11 +390,7 @@ export default function SearchBar({
   );
 
   // Implement hint icons for the search shortcuts on mac and the rest operating systems.
-  const isMac = isBrowser
-    ? /mac/i.test(
-        (navigator as any).userAgentData?.platform ?? navigator.platform
-      )
-    : false;
+  const isMac = isBrowser ? isMacPlatform() : false;
 
   // Sync the input value and focus state for SSR
   useEffect(
@@ -414,15 +413,15 @@ export default function SearchBar({
   );
 
   useEffect(() => {
-    if (!searchBarShortcut) {
+    if (!searchBarShortcut || !searchBarShortcutKeymap) {
       return;
     }
-    // Add shortcuts command/ctrl + K
+    
+    const parsedKeymap = parseKeymap(searchBarShortcutKeymap);
+    
+    // Add shortcuts based on custom keymap
     const handleShortcut = (event: KeyboardEvent): void => {
-      if (
-        (isMac ? event.metaKey : event.ctrlKey) &&
-        (event.key === "k" || event.key === "K")
-      ) {
+      if (matchesKeymap(event, parsedKeymap)) {
         event.preventDefault();
         searchBarRef.current?.focus();
         onInputFocus();
@@ -433,7 +432,7 @@ export default function SearchBar({
     return () => {
       document.removeEventListener("keydown", handleShortcut);
     };
-  }, [isMac, onInputFocus]);
+  }, [onInputFocus, searchBarShortcutKeymap]);
 
   const onClearSearch = useCallback(() => {
     const params = new URLSearchParams(location.search);
@@ -485,10 +484,11 @@ export default function SearchBar({
             ✕
           </button>
         ) : (
-          isBrowser && (
+          isBrowser && searchBarShortcutKeymap && (
             <div className={styles.searchHintContainer}>
-              <kbd className={styles.searchHint}>{isMac ? "⌘" : "ctrl"}</kbd>
-              <kbd className={styles.searchHint}>K</kbd>
+              {getKeymapHints(searchBarShortcutKeymap, isMac).map((hint, index) => (
+                <kbd key={index} className={styles.searchHint}>{hint}</kbd>
+              ))}
             </div>
           )
         ))}

docusaurus-search-local/src/client/utils/keymap.spec.ts

@@ -0,0 +1,186 @@
+import { parseKeymap, matchesKeymap, getKeymapHints } from './keymap';
+import * as platformModule from './platform';
+
+// Mock the platform module
+jest.mock('./platform');
+
+describe('keymap utility functions', () => {
+  const mockIsMacPlatform = jest.mocked(platformModule.isMacPlatform);
+
+  beforeEach(() => {
+    mockIsMacPlatform.mockClear();
+  });
+  describe('parseKeymap', () => {
+    test('should parse single key', () => {
+      const result = parseKeymap('s');
+      expect(result).toEqual({
+        key: 's',
+        ctrl: false,
+        alt: false,
+        shift: false,
+        meta: false,
+      });
+    });
+
+    test('should parse ctrl+k', () => {
+      const result = parseKeymap('ctrl+k');
+      expect(result).toEqual({
+        key: 'k',
+        ctrl: true,
+        alt: false,
+        shift: false,
+        meta: false,
+      });
+    });
+
+    test('should parse cmd+k', () => {
+      const result = parseKeymap('cmd+k');
+      expect(result).toEqual({
+        key: 'k',
+        ctrl: false,
+        alt: false,
+        shift: false,
+        meta: true,
+      });
+    });
+
+    test('should parse mod+k on Mac-like platform', () => {
+      mockIsMacPlatform.mockReturnValue(true);
+
+      const result = parseKeymap('mod+k');
+      expect(result).toEqual({
+        key: 'k',
+        ctrl: false,
+        alt: false,
+        shift: false,
+        meta: true,
+      });
+    });
+
+    test('should parse mod+k on non-Mac platform', () => {
+      mockIsMacPlatform.mockReturnValue(false);
+
+      const result = parseKeymap('mod+k');
+      expect(result).toEqual({
+        key: 'k',
+        ctrl: true,
+        alt: false,
+        shift: false,
+        meta: false,
+      });
+    });
+
+    test('should parse complex combination', () => {
+      const result = parseKeymap('ctrl+shift+alt+f');
+      expect(result).toEqual({
+        key: 'f',
+        ctrl: true,
+        alt: true,
+        shift: true,
+        meta: false,
+      });
+    });
+
+    test('should handle whitespace', () => {
+      const result = parseKeymap(' ctrl + k ');
+      expect(result).toEqual({
+        key: 'k',
+        ctrl: true,
+        alt: false,
+        shift: false,
+        meta: false,
+      });
+    });
+  });
+
+  describe('matchesKeymap', () => {
+    test('should match single key', () => {
+      const keymap = parseKeymap('s');
+      const event = {
+        key: 's',
+        ctrlKey: false,
+        altKey: false,
+        shiftKey: false,
+        metaKey: false,
+      } as KeyboardEvent;
+      
+      expect(matchesKeymap(event, keymap)).toBe(true);
+    });
+
+    test('should match ctrl+k', () => {
+      const keymap = parseKeymap('ctrl+k');
+      const event = {
+        key: 'k',
+        ctrlKey: true,
+        altKey: false,
+        shiftKey: false,
+        metaKey: false,
+      } as KeyboardEvent;
+      
+      expect(matchesKeymap(event, keymap)).toBe(true);
+    });
+
+    test('should not match if modifiers differ', () => {
+      const keymap = parseKeymap('ctrl+k');
+      const event = {
+        key: 'k',
+        ctrlKey: false,
+        altKey: false,
+        shiftKey: false,
+        metaKey: false,
+      } as KeyboardEvent;
+      
+      expect(matchesKeymap(event, keymap)).toBe(false);
+    });
+
+    test('should handle case insensitivity', () => {
+      const keymap = parseKeymap('ctrl+k');
+      const event = {
+        key: 'K',
+        ctrlKey: true,
+        altKey: false,
+        shiftKey: false,
+        metaKey: false,
+      } as KeyboardEvent;
+      
+      expect(matchesKeymap(event, keymap)).toBe(true);
+    });
+  });
+
+  describe('getKeymapHints', () => {
+    test('should generate hints for single key', () => {
+      const hints = getKeymapHints('s', false);
+      expect(hints).toEqual(['S']);
+    });
+
+    test('should generate hints for ctrl+k on non-Mac', () => {
+      const hints = getKeymapHints('ctrl+k', false);
+      expect(hints).toEqual(['ctrl', 'K']);
+    });
+
+    test('should generate hints for cmd+k on Mac', () => {
+      const hints = getKeymapHints('cmd+k', true);
+      expect(hints).toEqual(['⌘', 'K']);
+    });
+
+    test('should generate hints for mod+k on Mac', () => {
+      const hints = getKeymapHints('mod+k', true);
+      expect(hints).toEqual(['⌘', 'K']);
+    });
+
+    test('should generate hints for mod+k on non-Mac', () => {
+      const hints = getKeymapHints('mod+k', false);
+      expect(hints).toEqual(['ctrl', 'K']);
+    });
+
+    test('should generate hints for complex combination on Mac', () => {
+      const hints = getKeymapHints('ctrl+shift+alt+f', true);
+      expect(hints).toEqual(['ctrl', '⌥', '⇧', 'F']);
+    });
+
+    test('should generate hints for complex combination on non-Mac', () => {
+      const hints = getKeymapHints('ctrl+shift+alt+f', false);
+      expect(hints).toEqual(['ctrl', 'alt', 'shift', 'F']);
+    });
+  });
+});

docusaurus-search-local/src/client/utils/keymap.ts

@@ -0,0 +1,93 @@
+import { isMacPlatform } from './platform';
+
+export interface ParsedKeymap {
+  key: string;
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+  meta: boolean;
+}
+
+export function parseKeymap(keymap: string): ParsedKeymap {
+  const parts = keymap.toLowerCase().split('+');
+  const result: ParsedKeymap = {
+    key: '',
+    ctrl: false,
+    alt: false,
+    shift: false,
+    meta: false,
+  };
+
+  // Detect if we're on Mac to handle 'mod' appropriately
+  const isMac = isMacPlatform();
+
+  for (const part of parts) {
+    const trimmed = part.trim();
+    switch (trimmed) {
+      case 'ctrl':
+        result.ctrl = true;
+        break;
+      case 'cmd':
+        result.meta = true;
+        break;
+      case 'mod':
+        if (isMac) {
+          result.meta = true;
+        } else {
+          result.ctrl = true;
+        }
+        break;
+      case 'alt':
+        result.alt = true;
+        break;
+      case 'shift':
+        result.shift = true;
+        break;
+      default:
+        result.key = trimmed;
+        break;
+    }
+  }
+
+  return result;
+}
+
+export function matchesKeymap(event: KeyboardEvent, keymap: ParsedKeymap): boolean {
+  return (
+    event.key.toLowerCase() === keymap.key &&
+    event.ctrlKey === keymap.ctrl &&
+    event.altKey === keymap.alt &&
+    event.shiftKey === keymap.shift &&
+    event.metaKey === keymap.meta
+  );
+}
+
+export function getKeymapHints(keymap: string, isMac: boolean): string[] {
+  const parsedKeymap = parseKeymap(keymap);
+  const hints: string[] = [];
+
+  // Handle original keymap string to detect 'mod' for proper hint display
+  const parts = keymap.toLowerCase().split('+').map(p => p.trim());
+  const hasMod = parts.includes('mod');
+
+  if (parsedKeymap.ctrl && !hasMod) {
+    hints.push('ctrl');
+  }
+  if (parsedKeymap.meta && !hasMod) {
+    hints.push(isMac ? '⌘' : 'cmd');
+  }
+  if (hasMod) {
+    hints.push(isMac ? '⌘' : 'ctrl');
+  }
+  if (parsedKeymap.alt) {
+    hints.push(isMac ? '⌥' : 'alt');
+  }
+  if (parsedKeymap.shift) {
+    hints.push(isMac ? '⇧' : 'shift');
+  }
+  if (parsedKeymap.key) {
+    hints.push(parsedKeymap.key.toUpperCase());
+  }
+
+  return hints;
+}