refactor: Replace react-hotkeys with custom hook (#35425)

app/javascript/mastodon/components/hotkeys/hotkeys.stories.tsx

@@ -0,0 +1,171 @@
+import { useState } from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect } from 'storybook/test';
+
+import type { HandlerMap } from '.';
+import { Hotkeys } from '.';
+
+const meta = {
+  title: 'Components/Hotkeys',
+  component: Hotkeys,
+  args: {
+    global: undefined,
+    focusable: undefined,
+    handlers: {},
+  },
+  tags: ['test'],
+} satisfies Meta<typeof Hotkeys>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const hotkeyTest: Story['play'] = async ({ canvas, userEvent }) => {
+  async function confirmHotkey(name: string, shouldFind = true) {
+    // 'status' is the role of the 'output' element
+    const output = await canvas.findByRole('status');
+    if (shouldFind) {
+      await expect(output).toHaveTextContent(name);
+    } else {
+      await expect(output).not.toHaveTextContent(name);
+    }
+  }
+
+  const button = await canvas.findByRole('button');
+  await userEvent.click(button);
+
+  await userEvent.keyboard('n');
+  await confirmHotkey('new');
+
+  await userEvent.keyboard('/');
+  await confirmHotkey('search');
+
+  await userEvent.keyboard('o');
+  await confirmHotkey('open');
+
+  await userEvent.keyboard('{Alt>}N{/Alt}');
+  await confirmHotkey('forceNew');
+
+  await userEvent.keyboard('gh');
+  await confirmHotkey('goToHome');
+
+  await userEvent.keyboard('gn');
+  await confirmHotkey('goToNotifications');
+
+  await userEvent.keyboard('gf');
+  await confirmHotkey('goToFavourites');
+
+  /**
+   * Ensure that hotkeys are not triggered when certain
+   * interactive elements are focused:
+   */
+
+  await userEvent.keyboard('{enter}');
+  await confirmHotkey('open', false);
+
+  const input = await canvas.findByRole('textbox');
+  await userEvent.click(input);
+
+  await userEvent.keyboard('n');
+  await confirmHotkey('new', false);
+
+  await userEvent.keyboard('{backspace}');
+  await confirmHotkey('None', false);
+
+  /**
+   * Reset playground:
+   */
+
+  await userEvent.click(button);
+  await userEvent.keyboard('{backspace}');
+};
+
+export const Default = {
+  render: function Render() {
+    const [matchedHotkey, setMatchedHotkey] = useState<keyof HandlerMap | null>(
+      null,
+    );
+
+    const handlers = {
+      back: () => {
+        setMatchedHotkey(null);
+      },
+      new: () => {
+        setMatchedHotkey('new');
+      },
+      forceNew: () => {
+        setMatchedHotkey('forceNew');
+      },
+      search: () => {
+        setMatchedHotkey('search');
+      },
+      open: () => {
+        setMatchedHotkey('open');
+      },
+      goToHome: () => {
+        setMatchedHotkey('goToHome');
+      },
+      goToNotifications: () => {
+        setMatchedHotkey('goToNotifications');
+      },
+      goToFavourites: () => {
+        setMatchedHotkey('goToFavourites');
+      },
+    };
+
+    return (
+      <Hotkeys handlers={handlers}>
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 8,
+            padding: '1em',
+            border: '1px dashed #ccc',
+            fontSize: 14,
+            color: '#222',
+          }}
+        >
+          <h1
+            style={{
+              fontSize: 22,
+              marginBottom: '0.3em',
+            }}
+          >
+            Hotkey playground
+          </h1>
+          <p>
+            Last pressed hotkey: <output>{matchedHotkey ?? 'None'}</output>
+          </p>
+          <p>
+            Click within the dashed border and press the &quot;<kbd>n</kbd>
+            &quot; or &quot;<kbd>/</kbd>&quot; key. Press &quot;
+            <kbd>Backspace</kbd>&quot; to clear the displayed hotkey.
+          </p>
+          <p>
+            Try typing a sequence, like &quot;<kbd>g</kbd>&quot; shortly
+            followed by &quot;<kbd>h</kbd>&quot;, &quot;<kbd>n</kbd>&quot;, or
+            &quot;<kbd>f</kbd>&quot;
+          </p>
+          <p>
+            Note that this playground doesn&apos;t support all hotkeys we use in
+            the app.
+          </p>
+          <p>
+            When a <button>Button</button> is focused, &quot;
+            <kbd>Enter</kbd>
+            &quot; should not trigger &quot;open&quot;, but &quot;<kbd>o</kbd>
+            &quot; should.
+          </p>
+          <p>
+            When an input element is focused, hotkeys should not interfere with
+            regular typing:
+          </p>
+          <input type='text' />
+        </div>
+      </Hotkeys>
+    );
+  },
+  play: hotkeyTest,
+};

app/javascript/mastodon/components/hotkeys/index.tsx

@@ -0,0 +1,282 @@
+import { useEffect, useRef } from 'react';
+
+import { normalizeKey, isKeyboardEvent } from './utils';
+
+/**
+ * In case of multiple hotkeys matching the pressed key(s),
+ * the hotkey with a higher priority is selected. All others
+ * are ignored.
+ */
+const hotkeyPriority = {
+  singleKey: 0,
+  combo: 1,
+  sequence: 2,
+} as const;
+
+/**
+ * This type of function receives a keyboard event and an array of
+ * previously pressed keys (within the last second), and returns
+ * `isMatch` (whether the pressed keys match a hotkey) and `priority`
+ * (a weighting used to resolve conflicts when two hotkeys match the
+ * pressed keys)
+ */
+type KeyMatcher = (
+  event: KeyboardEvent,
+  bufferedKeys?: string[],
+) => {
+  /**
+   * Whether the event.key matches the hotkey
+   */
+  isMatch: boolean;
+  /**
+   * If there are multiple matching hotkeys, the
+   * first one with the highest priority will be handled
+   */
+  priority: (typeof hotkeyPriority)[keyof typeof hotkeyPriority];
+};
+
+/**
+ * Matches a single key
+ */
+function just(keyName: string): KeyMatcher {
+  return (event) => ({
+    isMatch: normalizeKey(event.key) === keyName,
+    priority: hotkeyPriority.singleKey,
+  });
+}
+
+/**
+ * Matches any single key out of those provided
+ */
+function any(...keys: string[]): KeyMatcher {
+  return (event) => ({
+    isMatch: keys.some((keyName) => just(keyName)(event).isMatch),
+    priority: hotkeyPriority.singleKey,
+  });
+}
+
+/**
+ * Matches a single key combined with the option/alt modifier
+ */
+function optionPlus(key: string): KeyMatcher {
+  return (event) => ({
+    // Matching against event.code here as alt combos are often
+    // mapped to other characters
+    isMatch: event.altKey && event.code === `Key${key.toUpperCase()}`,
+    priority: hotkeyPriority.combo,
+  });
+}
+
+/**
+ * Matches when all provided keys are pressed in sequence.
+ */
+function sequence(...sequence: string[]): KeyMatcher {
+  return (event, bufferedKeys) => {
+    const lastKeyInSequence = sequence.at(-1);
+    const startOfSequence = sequence.slice(0, -1);
+    const relevantBufferedKeys = bufferedKeys?.slice(-startOfSequence.length);
+
+    const bufferMatchesStartOfSequence =
+      !!relevantBufferedKeys &&
+      startOfSequence.join('') === relevantBufferedKeys.join('');
+
+    return {
+      isMatch:
+        bufferMatchesStartOfSequence &&
+        normalizeKey(event.key) === lastKeyInSequence,
+      priority: hotkeyPriority.sequence,
+    };
+  };
+}
+
+/**
+ * This is a map of all global hotkeys we support.
+ * To trigger a hotkey, a handler with a matching name must be
+ * provided to the `useHotkeys` hook or `Hotkeys` component.
+ */
+const hotkeyMatcherMap = {
+  help: just('?'),
+  search: any('s', '/'),
+  back: just('backspace'),
+  new: just('n'),
+  forceNew: optionPlus('n'),
+  focusColumn: any('1', '2', '3', '4', '5', '6', '7', '8', '9'),
+  reply: just('r'),
+  favourite: just('f'),
+  boost: just('b'),
+  mention: just('m'),
+  open: any('enter', 'o'),
+  openProfile: just('p'),
+  moveDown: any('down', 'j'),
+  moveUp: any('up', 'k'),
+  toggleHidden: just('x'),
+  toggleSensitive: just('h'),
+  toggleComposeSpoilers: optionPlus('x'),
+  openMedia: just('e'),
+  onTranslate: just('t'),
+  goToHome: sequence('g', 'h'),
+  goToNotifications: sequence('g', 'n'),
+  goToLocal: sequence('g', 'l'),
+  goToFederated: sequence('g', 't'),
+  goToDirect: sequence('g', 'd'),
+  goToStart: sequence('g', 's'),
+  goToFavourites: sequence('g', 'f'),
+  goToPinned: sequence('g', 'p'),
+  goToProfile: sequence('g', 'u'),
+  goToBlocked: sequence('g', 'b'),
+  goToMuted: sequence('g', 'm'),
+  goToRequests: sequence('g', 'r'),
+  cheat: sequence(
+    'up',
+    'up',
+    'down',
+    'down',
+    'left',
+    'right',
+    'left',
+    'right',
+    'b',
+    'a',
+    'enter',
+  ),
+} as const;
+
+type HotkeyName = keyof typeof hotkeyMatcherMap;
+
+export type HandlerMap = Partial<
+  Record<HotkeyName, (event: KeyboardEvent) => void>
+>;
+
+export function useHotkeys<T extends HTMLElement>(handlers: HandlerMap) {
+  const ref = useRef<T>(null);
+  const bufferedKeys = useRef<string[]>([]);
+  const sequenceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  /**
+   * Store the latest handlers object in a ref so we don't need to
+   * add it as a dependency to the main event listener effect
+   */
+  const handlersRef = useRef(handlers);
+  useEffect(() => {
+    handlersRef.current = handlers;
+  }, [handlers]);
+
+  useEffect(() => {
+    const element = ref.current ?? document;
+
+    function listener(event: Event) {
+      // Ignore key presses from input, textarea, or select elements
+      const tagName = (event.target as HTMLElement).tagName.toLowerCase();
+      const shouldHandleEvent =
+        isKeyboardEvent(event) &&
+        !event.defaultPrevented &&
+        !['input', 'textarea', 'select'].includes(tagName) &&
+        !(
+          ['a', 'button'].includes(tagName) &&
+          normalizeKey(event.key) === 'enter'
+        );
+
+      if (shouldHandleEvent) {
+        const matchCandidates: {
+          handler: (event: KeyboardEvent) => void;
+          priority: number;
+        }[] = [];
+
+        (Object.keys(hotkeyMatcherMap) as HotkeyName[]).forEach(
+          (handlerName) => {
+            const handler = handlersRef.current[handlerName];
+
+            if (handler) {
+              const hotkeyMatcher = hotkeyMatcherMap[handlerName];
+
+              const { isMatch, priority } = hotkeyMatcher(
+                event,
+                bufferedKeys.current,
+              );
+
+              if (isMatch) {
+                matchCandidates.push({ handler, priority });
+              }
+            }
+          },
+        );
+
+        // Sort all matches by priority
+        matchCandidates.sort((a, b) => b.priority - a.priority);
+
+        const bestMatchingHandler = matchCandidates.at(0)?.handler;
+        if (bestMatchingHandler) {
+          bestMatchingHandler(event);
+          event.stopPropagation();
+          event.preventDefault();
+        }
+
+        // Add last keypress to buffer
+        bufferedKeys.current.push(normalizeKey(event.key));
+
+        // Reset the timeout
+        if (sequenceTimer.current) {
+          clearTimeout(sequenceTimer.current);
+        }
+        sequenceTimer.current = setTimeout(() => {
+          bufferedKeys.current = [];
+        }, 1000);
+      }
+    }
+    element.addEventListener('keydown', listener);
+
+    return () => {
+      element.removeEventListener('keydown', listener);
+      if (sequenceTimer.current) {
+        clearTimeout(sequenceTimer.current);
+      }
+    };
+  }, []);
+
+  return ref;
+}
+
+/**
+ * The Hotkeys component allows us to globally register keyboard combinations
+ * under a name and assign actions to them, either globally or scoped to a portion
+ * of the app.
+ *
+ * ### How to use
+ *
+ * To add a new hotkey, add its key combination to the `hotkeyMatcherMap` object
+ * and give it a name.
+ *
+ * Use the `<Hotkeys>` component or the `useHotkeys` hook in the part of of the app
+ * where you want to handle the action, and pass in a handlers object.
+ *
+ * ```tsx
+ * <Hotkeys handlers={{open: openStatus}} />
+ * ```
+ *
+ * Now this function will be called when the 'open' hotkey is pressed by the user.
+ */
+export const Hotkeys: React.FC<{
+  /**
+   * An object containing functions to be run when a hotkey is pressed.
+   * The key must be the name of a registered hotkey, e.g. "help" or "search"
+   */
+  handlers: HandlerMap;
+  /**
+   * When enabled, hotkeys will be matched against the document root
+   * rather than only inside of this component's DOM node.
+   */
+  global?: boolean;
+  /**
+   * Allow the rendered `div` to be focused
+   */
+  focusable?: boolean;
+  children: React.ReactNode;
+}> = ({ handlers, global, focusable = true, children }) => {
+  const ref = useHotkeys<HTMLDivElement>(handlers);
+
+  return (
+    <div ref={global ? undefined : ref} tabIndex={focusable ? -1 : undefined}>
+      {children}
+    </div>
+  );
+};

app/javascript/mastodon/components/hotkeys/utils.ts

@@ -0,0 +1,29 @@
+export function isKeyboardEvent(event: Event): event is KeyboardEvent {
+  return 'key' in event;
+}
+
+export function normalizeKey(key: string): string {
+  const lowerKey = key.toLowerCase();
+
+  switch (lowerKey) {
+    case ' ':
+    case 'spacebar': // for older browsers
+      return 'space';
+
+    case 'arrowup':
+      return 'up';
+    case 'arrowdown':
+      return 'down';
+    case 'arrowleft':
+      return 'left';
+    case 'arrowright':
+      return 'right';
+
+    case 'esc':
+    case 'escape':
+      return 'escape';
+
+    default:
+      return lowerKey;
+  }
+}