From 7cef2dfbd524d7e8c41882fb11d8b38b728a79be Mon Sep 17 00:00:00 2001
From: Max Patiiuk <max@patii.uk>
Date: Sat, 13 Jul 2024 07:34:19 -0700
Subject: [PATCH] feat(Preferences): begin adding keyboard shortcuts

---
 .../lib/components/FormSliders/Slider.tsx     |  16 +-
 .../Preferences/KeyboardContext.tsx           | 185 ++++++++++++++++++
 .../Preferences/KeyboardShortcut.tsx          | 172 ++++++++++++++++
 .../Preferences/UserDefinitions.tsx           |  41 +++-
 .../frontend/js_src/lib/localization/forms.ts |  46 +++--
 .../js_src/lib/localization/preferences.ts    |  17 ++
 6 files changed, 453 insertions(+), 24 deletions(-)
 create mode 100644 specifyweb/frontend/js_src/lib/components/Preferences/KeyboardContext.tsx
 create mode 100644 specifyweb/frontend/js_src/lib/components/Preferences/KeyboardShortcut.tsx

diff --git a/specifyweb/frontend/js_src/lib/components/FormSliders/Slider.tsx b/specifyweb/frontend/js_src/lib/components/FormSliders/Slider.tsx
index 6b5d9d90705..07e35ffc6e0 100644
--- a/specifyweb/frontend/js_src/lib/components/FormSliders/Slider.tsx
+++ b/specifyweb/frontend/js_src/lib/components/FormSliders/Slider.tsx
@@ -29,18 +29,18 @@ export function Slider({
   return count > 0 ? (
     <nav className="flex justify-center gap-2 print:hidden">
       <Button.Small
-        aria-label={formsText.firstRecord()}
+        aria-label={formsText.goToFirstRecord()}
         disabled={value === 0 || handleChange === undefined}
-        title={formsText.firstRecord()}
+        title={formsText.goToFirstRecord()}
         onClick={(): void => handleChange?.(0)}
       >
         {icons.chevronDoubleLeft}
       </Button.Small>
       <Button.Small
-        aria-label={formsText.previousRecord()}
+        aria-label={formsText.goToPreviousRecord()}
         className="px-4 dark:bg-neutral-500"
         disabled={value === 0 || handleChange === undefined}
-        title={formsText.previousRecord()}
+        title={formsText.goToPreviousRecord()}
         onClick={(): void => handleChange?.(value - 1)}
       >
         {icons.chevronLeft}
@@ -84,18 +84,18 @@ export function Slider({
         <span>{count}</span>
       </div>
       <Button.Small
-        aria-label={formsText.nextRecord()}
+        aria-label={formsText.goToNextRecord()}
         className="px-4 dark:bg-neutral-500"
         disabled={value + 1 === count || handleChange === undefined}
-        title={formsText.nextRecord()}
+        title={formsText.goToNextRecord()}
         onClick={(): void => handleChange?.(value + 1)}
       >
         {icons.chevronRight}
       </Button.Small>
       <Button.Small
-        aria-label={formsText.lastRecord()}
+        aria-label={formsText.goToLastRecord()}
         disabled={value + 1 === count || handleChange === undefined}
-        title={formsText.lastRecord()}
+        title={formsText.goToLastRecord()}
         onClick={(): void => handleChange?.(count - 1)}
       >
         {icons.chevronDoubleRight}
diff --git a/specifyweb/frontend/js_src/lib/components/Preferences/KeyboardContext.tsx b/specifyweb/frontend/js_src/lib/components/Preferences/KeyboardContext.tsx
new file mode 100644
index 00000000000..5edc428f0ca
--- /dev/null
+++ b/specifyweb/frontend/js_src/lib/components/Preferences/KeyboardContext.tsx
@@ -0,0 +1,185 @@
+/**
+ * Allows to register a key listener
+ */
+
+import type { RA, RR } from '../../utils/types';
+
+/**
+ * Because operating systems, browsers and browser extensions define many
+ * keyboard shortcuts, many of which differ between operating systems, the set
+ * of free keyboard shortcuts is quite small so it's difficult to have one
+ * shortcut that works on all 3 platforms.
+ *
+ * To provide flexibility, without complicating the UI for people who only use
+ * Specify on a single platform, we do the following:
+ * - UI allows you to set keyboard shortcuts for the current platform only
+ * - If you set keyboard shortcut on any platform, that shortcut is used on all
+ *   platforms, unless you explicitly edited the shortcut on the other platform
+ * - If keyboard shortcut was not explicitly set, the default shortcut, if any
+ *   will be used
+ */
+export type KeyboardShortcuts = Partial<RR<Platform, RA<string> | undefined>>;
+
+type Platform = 'mac' | 'other' | 'windows';
+const platform: Platform =
+  navigator.platform.toLowerCase().includes('mac') ||
+  // Check for iphone || ipad || ipod
+  navigator.platform.toLowerCase().includes('ip')
+    ? 'mac'
+    : navigator.platform.toLowerCase().includes('win')
+    ? 'windows'
+    : 'other';
+
+const modifierKeys = ['alt', 'control', 'meta', 'shift'];
+type ModifierKey = typeof modifierKeys[number];
+const modifierKeyNames = new Set(modifierKeys);
+
+/**
+ * To keep the event listener as fast as possible, we are not looping though all
+ * set keyboard shortcuts and checking if any matches the set value - instead,
+ * the registered shortcuts are stored in this hashmap, making it very easy
+ * to check if a listener for current key combination exists.
+ */
+const listeners = new Map<string, () => void>();
+
+/**
+ * When setting a keyboard shortcut in user preferences, we want to:
+ * - Prevent any other shortcut from reacting
+ * - Read what keys were pressed
+ */
+let interceptor: ((keys: string) => void) | undefined;
+export function setKeyboardEventInterceptor(
+  callback: typeof interceptor
+): void {
+  interceptor = callback;
+}
+
+/*
+ * FIXME: handle case when key shortcut is not set for current platform
+ * FIXME: add test for default preferences containing non-existing shortcuts
+ * FIXME: add test for having shortcuts sorted
+ * FIXME: add test for not binding defaults to Enter/Tab/Space/Escape other forbidden keys (ask ChatGPT for full list)
+ * FIXME: make the useKeyboardShortcut() hook also return a localized keyboard
+ * shortcut string for usage in UI tooltips
+ */
+export function bindKeyboardShortcut(
+  shortcut: KeyboardShortcuts,
+  callback: () => void
+): () => void {
+  const shortcuts = shortcut[platform] ?? [];
+  shortcuts.forEach((string) => {
+    listeners.set(string, callback);
+  });
+  return () =>
+    shortcuts.forEach((string) => {
+      /*
+       * Another listener may have been set on this shortcut - only unset if we
+       * are still the active listener
+       */
+      const activeListener = listeners.get(string);
+      if (activeListener === callback) listeners.delete(string);
+    });
+}
+
+const keysToString = (modifiers: RA<ModifierKey>, keys: RA<string>): string =>
+  [...modifiers, ...keys].join('+');
+
+// eslint-disable-next-line functional/prefer-readonly-type
+const pressedKeys: string[] = [];
+
+document.addEventListener('keydown', (event) => {
+  if (shouldIgnoreKeyPress(event)) return;
+  if (pressedKeys.includes(event.key)) return;
+
+  pressedKeys.push(event.key);
+  pressedKeys.sort();
+
+  const modifiers = resolveModifiers(event);
+  const isEntering = isInInput(event);
+  // FIXME: should this include alt too?
+  const noModifiers = modifiers.length === 0 || modifiers[0] === 'Shift';
+  // Ignore single key shortcuts when in an input field
+  const ignore = noModifiers && isEntering;
+  if (ignore) return;
+
+  const keyString = keysToString(modifiers, pressedKeys);
+  const handler = interceptor ?? listeners.get(keyString);
+  if (typeof handler === 'function') {
+    handler(keyString);
+    /*
+     * Do this only after calling handler, so that if handler throws an
+     * exception, the event can still be handled normally by the browser
+     */
+    event.preventDefault();
+    event.stopPropagation();
+  }
+});
+
+function shouldIgnoreKeyPress(event: KeyboardEvent): boolean {
+  const key = event.key;
+
+  if (event.isComposing || event.repeat) return true;
+
+  /**
+   * Do not allow binding keyboard shortcuts to Tab key. That key is
+   * important for accessibility and for keyboard navigation. Without it
+   * you won't be able to tab your way to the "Save" button to save the
+   * keyboard shortcut)
+   */
+  if (key === 'Tab') return true;
+  // See https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key#value
+  if (key === 'Dead' || key === 'Unidentified') return true;
+  // FIXME: ignore all modifiers: https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values#modifier_keys
+  const isModifier = modifierKeyNames.has(event.key.toLowerCase());
+
+  return !isModifier;
+}
+
+const resolveModifiers = (event: KeyboardEvent): RA<ModifierKey> =>
+  Object.entries({
+    // This order is important - keep it alphabetical
+    alt: event.altKey,
+    ctrl: event.ctrlKey,
+    meta: event.metaKey,
+    shift: event.shiftKey,
+  })
+    .filter(([_, isPressed]) => isPressed)
+    .map(([modifier]) => modifier);
+
+function isInInput(event: KeyboardEvent): boolean {
+  // Check if the event target is an editable element.
+  const target = event.target as HTMLElement;
+  return (
+    target.tagName === 'INPUT' ||
+    target.tagName === 'TEXTAREA' ||
+    target.isContentEditable
+  );
+}
+
+document.addEventListener(
+  'keyup',
+  (event) => {
+    if (shouldIgnoreKeyPress(event)) return;
+    const index = pressedKeys.indexOf(event.key);
+    if (index !== -1) pressedKeys.splice(index, 1);
+  },
+  { passive: true }
+);
+
+/**
+ * While key up should normally catch key release, that may not always be the
+ * case:
+ * - If key up occurred outside the browser window
+ * - If key up occurred inside of browser devtools
+ * - If key up was intercepted by something else (i.e browser extension)
+ */
+window.addEventListener(
+  'blur',
+  () => {
+    pressedKeys.length = 0;
+  },
+  { passive: true }
+);
+document.addEventListener('visibilitychange', () => {
+  if (document.hidden) pressedKeys.length = 0;
+});
diff --git a/specifyweb/frontend/js_src/lib/components/Preferences/KeyboardShortcut.tsx b/specifyweb/frontend/js_src/lib/components/Preferences/KeyboardShortcut.tsx
new file mode 100644
index 00000000000..06d20831df3
--- /dev/null
+++ b/specifyweb/frontend/js_src/lib/components/Preferences/KeyboardShortcut.tsx
@@ -0,0 +1,172 @@
+/**
+ * Logic for setting and listening to keyboard shortcuts
+ */
+
+import { platform, Platform } from '@floating-ui/react';
+import React from 'react';
+
+import { useTriggerState } from '../../hooks/useTriggerState';
+import { commonText } from '../../localization/common';
+import { preferencesText } from '../../localization/preferences';
+import { listen } from '../../utils/events';
+import type { RA } from '../../utils/types';
+import {
+  removeItem,
+  replaceItem,
+  replaceKey,
+  sortFunction,
+} from '../../utils/utils';
+import { Button } from '../Atoms/Button';
+import type {
+  KeyboardShortcutBinding,
+  KeyboardShortcuts,
+} from './KeyboardContext';
+import type { PreferenceRendererProps } from './types';
+
+const modifierLocalization = {
+  alt: preferencesText.alt(),
+  ctrl: preferencesText.ctrl(),
+  meta: preferencesText.meta(),
+  shift: preferencesText.shift(),
+};
+
+export function KeyboardShortcutPreferenceItem({
+  value,
+  onChange: handleChange,
+}: PreferenceRendererProps<KeyboardShortcuts>): JSX.Element {
+  const [editingIndex, setEditingIndex] = React.useState<number | false>(false);
+  const isEditing = typeof editingIndex === 'number';
+  const shortcuts = value[platform] ?? [];
+  const setShortcuts = (shortcuts: RA<KeyboardShortcutBinding>): void =>
+    handleChange(replaceKey(value, platform, shortcuts));
+
+  return (
+    <div className="flex flex-col gap-2">
+      {shortcuts.map((shortcut, index) => (
+        <EditKeyboardShortcut
+          key={index}
+          shortcut={shortcut}
+          onEditStart={
+            editingIndex === false
+              ? (): void => setEditingIndex(index)
+              : undefined
+          }
+          onSave={
+            editingIndex === index
+              ? (shortcut): void => {
+                  setShortcuts(
+                    shortcut === undefined
+                      ? removeItem(shortcuts, index)
+                      : replaceItem(shortcuts, index, shortcut)
+                  );
+                  setEditingIndex(false);
+                }
+              : undefined
+          }
+        />
+      ))}
+      <div className="flex items-end gap-2">
+        {!isEditing && (
+          <Button.Small
+            onClick={(): void => {
+              setShortcuts([...shortcuts, { modifiers: [], keys: [] }]);
+              setEditingIndex(shortcuts.length);
+            }}
+          >
+            {commonText.add()}
+          </Button.Small>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function EditKeyboardShortcut({
+  shortcut,
+  onSave: handleSave,
+  onEditStart: handleEditStart,
+}: {
+  readonly shortcut: KeyboardShortcutBinding;
+  readonly onSave:
+    | ((shortcut: KeyboardShortcutBinding | undefined) => void)
+    | undefined;
+  readonly onEditStart: (() => void) | undefined;
+}): JSX.Element {
+  const [localState, setLocalState] = useTriggerState(shortcut);
+  const { modifiers, keys } = localState;
+  const isEditing = typeof handleSave === 'function';
+
+  React.useEffect(() => {
+    if (isEditing) {
+      setLocalState({ modifiers: [], keys: [] });
+      return listen(
+        document,
+        'keydown',
+        (event) => {
+          if (ignoreKeyPress(event, false)) return;
+
+          if (event.key === 'Enter') handleSave(activeValue.current);
+          else {
+            const modifiers = resolveModifiers(event);
+            setLocalState((localState) => ({
+              modifiers: Array.from(
+                // eslint-disable-next-line unicorn/consistent-destructuring
+                new Set([...localState.modifiers, ...modifiers])
+              ).sort(sortFunction((key) => key)),
+              // eslint-disable-next-line unicorn/consistent-destructuring
+              keys: Array.from(new Set([...localState.keys, event.key])).sort(
+                sortFunction((key) => key)
+              ),
+            }));
+          }
+
+          event.preventDefault();
+          event.stopPropagation();
+        },
+        { capture: true }
+      );
+    }
+    return undefined;
+  }, [isEditing, setLocalState]);
+
+  const isEmpty = modifiers.length === 0 && keys.length === 0;
+  const activeValue = React.useRef(localState);
+  activeValue.current = isEmpty ? shortcut : localState;
+
+  return (
+    <div className="flex gap-2">
+      <div
+        aria-atomic
+        aria-live={isEditing ? 'polite' : undefined}
+        className="flex flex-1 flex-wrap items-center gap-2"
+      >
+        {isEditing && isEmpty ? preferencesText.pressKeys() : undefined}
+        {modifiers.map((modifier) => (
+          <Key key={modifier} label={modifierLocalization[modifier]} />
+        ))}
+        {keys.map((key) => (
+          <Key key={key} label={key} />
+        ))}
+      </div>
+      {isEditing && (
+        <Button.Small onClick={(): void => handleSave(undefined)}>
+          {commonText.remove()}
+        </Button.Small>
+      )}
+      <Button.Small
+        aria-pressed={isEditing ? true : undefined}
+        onClick={
+          isEditing
+            ? (): void => handleSave(activeValue.current)
+            : handleEditStart
+        }
+      >
+        {isEditing ? commonText.save() : commonText.edit()}
+      </Button.Small>
+    </div>
+  );
+}
+
+function Key({ label }: { readonly label: string }): JSX.Element {
+  return <span className="rounded bg-gray-200 p-2">{label}</span>;
+}
diff --git a/specifyweb/frontend/js_src/lib/components/Preferences/UserDefinitions.tsx b/specifyweb/frontend/js_src/lib/components/Preferences/UserDefinitions.tsx
index 53b31b4bebc..55819547793 100644
--- a/specifyweb/frontend/js_src/lib/components/Preferences/UserDefinitions.tsx
+++ b/specifyweb/frontend/js_src/lib/components/Preferences/UserDefinitions.tsx
@@ -42,6 +42,9 @@ import {
   LanguagePreferencesItem,
   SchemaLanguagePreferenceItem,
 } from '../Toolbar/Language';
+import type { KeyboardShortcuts } from './KeyboardContext';
+import { KeyboardShortcutBinding } from './KeyboardContext';
+import { KeyboardShortcutPreferenceItem } from './KeyboardShortcut';
 import type { MenuPreferences, WelcomePageMode } from './Renderers';
 import {
   CollectionSortOrderPreferenceItem,
@@ -51,7 +54,11 @@ import {
   HeaderItemsPreferenceItem,
   WelcomePageModePreferenceItem,
 } from './Renderers';
-import type { GenericPreferences, PreferencesVisibilityContext } from './types';
+import type {
+  GenericPreferences,
+  PreferenceItem,
+  PreferencesVisibilityContext,
+} from './types';
 import { definePref } from './types';
 
 const isLightMode = ({
@@ -74,6 +81,22 @@ const altKeyName = globalThis.navigator?.appVersion.includes('Mac')
 const tableLabel = (tableName: keyof Tables): LocalizedString =>
   genericTables[tableName]?.label ?? camelToHuman(tableName);
 
+const defineKeyboardShortcut = (
+  title: LocalizedString,
+  defaultValue: KeyboardShortcuts | string
+): PreferenceItem<KeyboardShortcuts> =>
+  definePref<KeyboardShortcuts>({
+    title,
+    requiresReload: false,
+    visible: true,
+    defaultValue:
+      typeof defaultValue === 'string'
+        ? { other: [defaultValue] }
+        : defaultValue,
+    renderer: KeyboardShortcutPreferenceItem,
+    container: 'label',
+  });
+
 export const userPreferenceDefinitions = {
   general: {
     title: preferencesText.general(),
@@ -1122,6 +1145,22 @@ export const userPreferenceDefinitions = {
               },
             ],
           }),
+          goToFirstRecord: defineKeyboardShortcut(
+            formsText.goToFirstRecord(),
+            'shift+M'
+          ),
+          goToPreviousRecord: defineKeyboardShortcut(
+            formsText.goToPreviousRecord(),
+            'shift+<'
+          ),
+          goToNextRecord: defineKeyboardShortcut(
+            formsText.goToNextRecord(),
+            'ctrl+ArrowDown'
+          ),
+          goToLastRecord: defineKeyboardShortcut(
+            formsText.goToLastRecord(),
+            'ctrl+ArrowDown'
+          ),
         },
       },
       formTable: {
diff --git a/specifyweb/frontend/js_src/lib/localization/forms.ts b/specifyweb/frontend/js_src/lib/localization/forms.ts
index e0f95960133..e8a404b4a60 100644
--- a/specifyweb/frontend/js_src/lib/localization/forms.ts
+++ b/specifyweb/frontend/js_src/lib/localization/forms.ts
@@ -330,6 +330,14 @@ export const formsText = createDictionary({
     'uk-ua': 'Перший запис',
     'de-ch': 'Erster Eintrag',
   },
+  goToFirstRecord: {
+    'en-us': 'Go to first record',
+    'ru-ru': 'Перейти к первой записи',
+    'es-es': 'Ir al primer registro',
+    'fr-fr': 'Aller au premier enregistrement',
+    'uk-ua': 'Перейти до першого запису',
+    'de-ch': 'Zum ersten Eintrag gehen',
+  },
   lastRecord: {
     'en-us': 'Last Record',
     'ru-ru': 'Последняя запись',
@@ -338,21 +346,29 @@ export const formsText = createDictionary({
     'uk-ua': 'Останній запис',
     'de-ch': 'Letzter Eintrag',
   },
-  previousRecord: {
-    'en-us': 'Previous Record',
-    'ru-ru': 'Предыдущая запись',
-    'es-es': 'Récord anterior',
-    'fr-fr': 'Enregistrement précédent',
-    'uk-ua': 'Попередній запис',
-    'de-ch': 'Bisherigen Rekord',
-  },
-  nextRecord: {
-    'en-us': 'Next Record',
-    'ru-ru': 'Следующая запись',
-    'es-es': 'Próximo registro',
-    'fr-fr': 'Enregistrement suivant',
-    'uk-ua': 'Наступний запис',
-    'de-ch': 'Nächster Datensatz',
+  goToLastRecord: {
+    'en-us': 'Go to last record',
+    'ru-ru': 'Перейти к последней записи',
+    'es-es': 'Ir al último registro',
+    'fr-fr': 'Aller au dernier enregistrement',
+    'uk-ua': 'Перейти до останнього запису',
+    'de-ch': 'Zum letzten Eintrag gehen',
+  },
+  goToPreviousRecord: {
+    'en-us': 'Go to previous record',
+    'ru-ru': 'Перейти к предыдущей записи',
+    'es-es': 'Ir al registro anterior',
+    'fr-fr': "Aller à l'enregistrement précédent",
+    'uk-ua': 'Перейти до попереднього запису',
+    'de-ch': 'Zum vorherigen Datensatz gehen',
+  },
+  goToNextRecord: {
+    'en-us': 'Go to next record',
+    'ru-ru': 'Перейти к следующей записи',
+    'es-es': 'Ir al siguiente registro',
+    'fr-fr': "Aller à l'enregistrement suivant",
+    'uk-ua': 'Перейти до наступного запису',
+    'de-ch': 'Zum nächsten Datensatz gehen',
   },
   currentRecord: {
     'en-us': 'Current object (out of {total:number|formatted})',
diff --git a/specifyweb/frontend/js_src/lib/localization/preferences.ts b/specifyweb/frontend/js_src/lib/localization/preferences.ts
index 26d0eb68c7a..b13598f4beb 100644
--- a/specifyweb/frontend/js_src/lib/localization/preferences.ts
+++ b/specifyweb/frontend/js_src/lib/localization/preferences.ts
@@ -1983,4 +1983,21 @@ export const preferencesText = createDictionary({
     'ru-ru': 'Добавить панель поиска на главную страницу',
     'uk-ua': 'Додайте рядок пошуку на головну сторінку',
   },
+  alt: {
+    comment: 'Alt key on the keyboard',
+    'en-us': 'Alt',
+  },
+  ctrl: {
+    comment: 'Ctrl key on the keyboard',
+    'en-us': 'Ctrl',
+  },
+  meta: {
+    comment: 'Meta key on the keyboard',
+    'en-us': 'Meta',
+  },
+  shift: {
+    comment: 'Shift key on the keyboard',
+    'en-us': 'Shift',
+  },
+  pressKeys: { 'en-us': 'Press desired key combinations...' },
 } as const);