[WIP] Implemented keybind module to handle keyboard shortcuts

frontend/src/lib/keybind.ts

@@ -0,0 +1,246 @@
+/**
+ * Enum to represent the key strings provided by {@link KeyboardEvent}
+ */
+export enum Keys {
+  J = 'j',
+  D = 'd',
+  K = 'k',
+  H = 'h',
+  V = 'v',
+  T = 't',
+  M = 'm',
+  L = 'l',
+  O = 'o',
+  S = 's',
+  SINGLE_QUOTE = "'",
+  FORWARD_SLASH = '/',
+  CTRL = 'Control',
+  ENTER = 'Enter',
+  ARROW_UP = 'ArrowUp',
+  ARROW_DOWN = 'ArrowDown',
+}
+
+// The type used to declare the key downs that will trigger the callback
+export interface KeybindCallback {
+  key: Keys;
+  callback: (e: KeyboardEvent) => void;
+  shift?: boolean;
+  ctrl?: boolean;
+  alt?: boolean;
+}
+
+/**
+ * Used to create and interface with key bindings
+ */
+export class Keybind {
+  // All of the keybindings to their callbacks
+  private bindings: KeybindCallback[];
+  private bindingEntries: Keys[];
+
+  /**
+   * Constructor
+   *
+   * @param bindings An array of {@link KeybindCallback}s to be evaluated and utilized with {@link Keybind:onKeyDown}.
+   */
+  constructor(bindings: KeybindCallback[]) {
+    this.bindings = bindings;
+    this.bindingEntries = this.bindings.map((x) => x.key);
+  }
+
+  /**
+   * Attempt to convert a string to {@link Keys} enum
+   *
+   * @param str - The string to attempt to convert
+   * @returns undefined if unable to convert, otherwise {@link Keys}
+   */
+  private keyEnumFromString(str: string): Keys | undefined {
+    for (const [_, key] of Object.entries(Keys)) {
+      if (key == str) return key;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Handler for `keydown` events
+   *
+   * @remarks
+   * Requires a wrapper function to pass in `useKeyboardShortcuts` boolean store.
+   *
+   * Will run the given callback if all requirements are met from an item in the
+   * previously given {@link KeybindCallback} array.
+   *
+   * @param e - The `keydown` event of `KeyboardEvent` type
+   * @param useKeyboardShortcuts - A boolean of the user's `useKeyboardShortcuts` preference
+   */
+  onKeyDown(e: KeyboardEvent, useKeyboardShortcuts: boolean) {
+    if (!useKeyboardShortcuts || e.repeat) return;
+
+    const enum_key = this.keyEnumFromString(e.key);
+
+    if (!(enum_key && this.bindingEntries.includes(enum_key))) return;
+
+    // Conditionals to be able to later compare to a potentially undefined binding.shift/.al/.ctrl
+    const shift = e.shiftKey ? true : undefined;
+    const ctrl = e.ctrlKey ? true : undefined;
+    const alt = e.altKey ? true : undefined;
+
+    const binding = this.bindings.find((binding) => binding.key === enum_key);
+    if (binding && binding.alt == alt && binding.shift == shift && binding.ctrl == ctrl) {
+      e.preventDefault();
+      binding.callback(e);
+    }
+  }
+}
+
+/*
+Search callbacks
+*/
+
+/**
+ * Used to indicate what direction {@link navigateResults} should go (up/down)
+ */
+type Direction = 1 | -1;
+
+/**
+ * Utilized to bring the next/previous result into focus
+ *
+ * @remarks
+ * Utilizes the element that is currently in focus and the given
+ * direction to determine where and how to traverse the array of
+ * results. Moves a single result per call.
+ *
+ * @param direction - How to maneuver through the result list (up/down), indicated by {@link Direction}
+ */
+const navigateResults = (direction: Direction) => {
+  const currentActive = document.activeElement;
+
+  const results = [...document.getElementsByClassName('result')] as HTMLElement[];
+  let currentResultIndex: number | null = null;
+  let newIndex = 0;
+
+  results.forEach((el, index) => {
+    if (el.contains(currentActive)) currentResultIndex = index;
+  });
+
+  if (currentResultIndex != null) {
+    newIndex = currentResultIndex + direction;
+    if (0 > newIndex || newIndex >= results.length) {
+      newIndex = currentResultIndex;
+    }
+  }
+
+  const nextResult = results[newIndex];
+
+  // Get the anchor element and focus it
+  (nextResult.getElementsByClassName('result-main-link')[0] as HTMLElement)?.focus();
+};
+
+/**
+ * Wrapper for {@link navigateResults} that will focus on the next result
+ */
+const focusNextResult = () => navigateResults(1);
+
+/**
+ * Wrapper for {@link navigateResults} that will focus on the previous result
+ */
+const focusPrevResult = () => navigateResults(-1);
+
+/**
+ * Focus the first result (if any)
+ */
+const focusMainResult = () => {
+  const results = document.getElementsByClassName('result-main-link');
+  if (results.length > 0) {
+    (results[0] as HTMLElement).focus();
+  }
+};
+
+/**
+ * Focus the search bar
+ */
+const focusSearchBar = () => {
+  (document.getElementById('searchbar') as HTMLInputElement)?.select();
+};
+
+/**
+ * Scroll to the top of the window and reset focus
+ */
+const scrollToTop = () => {
+  window.scrollTo({ top: 0, behavior: 'smooth' });
+  if (document.activeElement instanceof HTMLElement) {
+    document.activeElement.blur(); // reset focus
+  }
+};
+
+/**
+ * Redirect to the currently focused result
+ *
+ * @param e - The triggering {@link KeyboardEvent}
+ */
+const openResult = (e: KeyboardEvent) => {
+  if ((e.target as HTMLElement).className.includes('result-main-link')) {
+    const resultLink = e.target as HTMLAnchorElement;
+    window.location.href = resultLink.href;
+  } else {
+    const results = document.getElementsByClassName('result-main-link');
+    if (results.length > 0) {
+      window.location.href = (results[0] as HTMLAnchorElement).href;
+    }
+  }
+};
+
+/**
+ * Open the currently focused result in a new tab
+ *
+ * @remarks
+ * Requires pop-ups to be allowed for the window
+ *
+ * @param e - The triggering {@link KeyboardEvent}
+ */
+const openResultInNewTab = (e: KeyboardEvent) => {
+  // Ensure target event is a result url
+  if ((e.target as HTMLElement).className.includes('result-main-link')) {
+    const resultLink = e.target as HTMLAnchorElement;
+    window.open(resultLink.href, '_blank', 'noopener');
+  }
+};
+
+/**
+ * Do a domain search using the domain of the currently focused result
+ *
+ * @param e - The triggering {@link KeyboardEvent}
+ */
+const domainSearch = (e: KeyboardEvent) => {
+  // Ensure target event is a result url
+  if ((e.target as HTMLElement).className.includes('result-main-link')) {
+    const searchBar = document.getElementById('searchbar') as HTMLInputElement;
+    if (searchBar) {
+      // Parse the result url, pull out the hostname then resubmit search
+      const resultLink = new URL((e.target as HTMLAnchorElement)?.href);
+      searchBar.value += ` site:${resultLink.hostname}`;
+      searchBar.form?.submit();
+    }
+  }
+};
+
+/**
+ * Redirect to the `Did you mean:` link (if exists)
+ */
+const goToMisspellLink = () => {
+  const msLink = document.getElementById('misspell-link');
+  if (msLink) window.location.href = (msLink as HTMLAnchorElement).href;
+};
+
+// Packaged callbacks to keep imports clean
+export const searchCb = {
+  focusNextResult,
+  focusPrevResult,
+  focusMainResult,
+  focusSearchBar,
+  scrollToTop,
+  openResult,
+  openResultInNewTab,
+  domainSearch,
+  goToMisspellLink,
+};

frontend/src/lib/stores.ts

@@ -76,6 +76,9 @@ export const markPagesWithAdsStore = writableLocalStorage<boolean>(MARK_PAGES_WI
 const RESULTS_IN_NEW_TAB_KEY = 'resultsInNewTab';
 export const resultsInNewTab = writableLocalStorage<boolean>(RESULTS_IN_NEW_TAB_KEY, false);
 
+const USE_KEYBOARD_SHORTCUTS = 'useKeyboardShortcuts';
+export const useKeyboardShortcuts = writableLocalStorage<boolean>(USE_KEYBOARD_SHORTCUTS, true);
+
 const MARK_PAGES_WITH_PAYWALL_KEY = 'markPagesWithPaywall';
 export const markPagesWithPaywallStore = writableLocalStorage<boolean>(
   MARK_PAGES_WITH_PAYWALL_KEY,

frontend/src/routes/search/+page.svelte

@@ -7,7 +7,8 @@
   import RegionSelect from '$lib/components/RegionSelect.svelte';
   import type { DisplayedWebpage } from '$lib/api';
   import { onMount } from 'svelte';
-  import { searchQueryStore } from '$lib/stores';
+  import { searchQueryStore, useKeyboardShortcuts } from '$lib/stores';
+  import { Keys, Keybind, searchCb } from '$lib/keybind';
   import { flip } from 'svelte/animate';
   import Result from './Result.svelte';
   import Sidebar from './Sidebar.svelte';
@@ -24,6 +25,30 @@
 
   let modal: { top: number; left: number; site: DisplayedWebpage } | undefined;
 
+  const keybind = new Keybind([
+    { key: Keys.J, callback: searchCb.focusNextResult },
+    { key: Keys.ARROW_DOWN, callback: searchCb.focusNextResult },
+    { key: Keys.K, callback: searchCb.focusPrevResult },
+    { key: Keys.ARROW_UP, callback: searchCb.focusPrevResult },
+    { key: Keys.H, callback: searchCb.focusSearchBar },
+    { key: Keys.FORWARD_SLASH, callback: searchCb.focusSearchBar },
+    { key: Keys.V, callback: searchCb.openResultInNewTab },
+    { key: Keys.SINGLE_QUOTE, callback: searchCb.openResultInNewTab },
+    { key: Keys.T, callback: searchCb.scrollToTop },
+    { key: Keys.D, callback: searchCb.domainSearch },
+    { key: Keys.L, callback: searchCb.openResult },
+    { key: Keys.O, callback: searchCb.openResult },
+    { key: Keys.M, callback: searchCb.focusMainResult },
+    { key: Keys.S, callback: searchCb.goToMisspellLink },
+  ]);
+
+  const onKeyDown = (event: KeyboardEvent) => {
+    // Only call onKeyDown if the target is not an input element (ie. search bar)
+    if (!((event.target as HTMLElement).nodeName === 'INPUT')) {
+      keybind.onKeyDown(event, $useKeyboardShortcuts);
+    }
+  };
+
   onMount(() => {
     const listener = () => {
       modal = void 0;
@@ -67,6 +92,8 @@
   }
 </script>
 
+<svelte:window on:keydown={onKeyDown} />
+
 {#if modal}
   <Modal {query} {modal} />
 {/if}
@@ -110,6 +137,7 @@
           <div>
             Did you mean:{' '}
             <a
+              id="misspell-link"
               class="font-medium"
               href="/search?q={encodeURIComponent(results.spellCorrection.raw)}"
               >{#each results.spellCorrection.highlighted as frag}

frontend/src/routes/search/Result.svelte

@@ -24,7 +24,7 @@
   const dispatch = createEventDispatcher<{ modal: HTMLButtonElement }>();
 </script>
 
-<div class="flex min-w-0 grow flex-col space-y-0.5">
+<div class="result flex min-w-0 grow flex-col space-y-0.5">
   <div class="flex min-w-0">
     <div class="flex min-w-0 grow flex-col space-y-0.5">
       <div class="flex items-center text-sm">
@@ -37,7 +37,7 @@
         </ResultLink>
       </div>
       <ResultLink
-        _class="max-w-[calc(100%-30px)] truncate text-xl font-medium text-link visited:text-link-visited hover:underline"
+        _class="result-main-link max-w-[calc(100%-30px)] truncate text-xl font-medium text-link visited:text-link-visited hover:underline"
         title={webpage.title}
         href={webpage.url}
         {resultIndex}

frontend/src/routes/settings/+page.svelte

@@ -5,6 +5,7 @@
   import MarkPagesWithAdsSelect from './MarkPagesWithAdsSelect.svelte';
   import MarkPagesWithPaywallSelect from './MarkPagesWithPaywallSelect.svelte';
   import ResultsInNewTabs from './ResultsInNewTabs.svelte';
+  import UseKeyboardShortcuts from './UseKeyboardShortcuts.svelte';
 
   const settings = [
     {
@@ -38,6 +39,11 @@
       description: 'Keep the search results window open and have links open in new tabs',
       type: 'results-in-new-tabs',
     },
+    {
+      title: 'Keyboard shortcuts',
+      description: 'Enables the use of keyboard shortcuts on the site',
+      type: 'use-keeb-shortcuts',
+    },
   ] as const;
 </script>
 
@@ -65,6 +71,8 @@
                 <MarkPagesWithPaywallSelect />
               {:else if setting.type == 'results-in-new-tabs'}
                 <ResultsInNewTabs />
+              {:else if setting.type == 'use-keeb-shortcuts'}
+                <UseKeyboardShortcuts />
               {/if}
             </div>
           </div>

frontend/src/routes/settings/UseKeyboardShortcuts.svelte

@@ -0,0 +1,6 @@
+<script lang="ts">
+  import { useKeyboardShortcuts } from '$lib/stores';
+  import RadioSelect from './RadioSelect.svelte';
+</script>
+
+<RadioSelect store={useKeyboardShortcuts} prefix="use-keeb-shortcuts" />