Typeahead

import { useCallback, useEffect, useMemo, useRef } from "react";
import type { KeyboardEvent } from "react";

/** Long enough to type a word, short enough that a pause starts a new search. */
export const TYPEAHEAD_TIMEOUT = 1000;

export interface TypeaheadItem {
  readonly key: string;
  readonly text: string;
}

const collator = new Intl.Collator(undefined, { sensitivity: "base", usage: "search" });

function startsWith(text: string, query: string): boolean {
  const head = Array.from(text.normalize("NFC")).slice(0, Array.from(query).length).join("");
  return collator.compare(head, query) === 0;
}

/**
 * The item a typed query lands on, ignoring case and accents. A single character
 * — or the same character repeated — moves on to the next item starting with it,
 * so pressing a letter again cycles; a longer query may stay where it is, so
 * typing a word does not skip past the match it has already found.
 *
 * An item's `text` is read only as the search reaches it, and the search stops
 * at its match: `text` may be a getter over something costly to read.
 */
export function matchTypeahead(
  items: readonly TypeaheadItem[],
  query: string,
  currentKey: string | null,
): string | null {
  const characters = Array.from(query.normalize("NFC"));
  if (characters.length === 0) return null;
  const repeated = characters.every((c) => c === characters[0]);
  const search = repeated ? characters[0]! : characters.join("");

  const current = items.findIndex((item) => item.key === currentKey);
  const start = current + (repeated ? 1 : 0);
  for (let offset = 0; offset < items.length; offset += 1) {
    const item = items[(Math.max(start, 0) + offset) % items.length]!;
    if (startsWith(item.text, search)) return item.key;
  }
  return null;
}

export interface TypeaheadHandler {
  (event: KeyboardEvent): boolean;
  readonly reset: () => void;
}

const MODIFIERS = new Set(["Shift", "Control", "Alt", "Meta", "CapsLock", "AltGraph", "Fn"]);

/**
 * Accumulates typed characters into a query. Returns a key handler that reports
 * whether it consumed the key. Space counts as a character once a query has
 * started, so "New York" can be typed; before that it is left to the component.
 * Any other key — an arrow, Home — ends the query, so the next character starts
 * a new one from where focus has moved. `reset` ends it from outside: when focus
 * leaves, what is typed on return is a new query.
 */
export function useTypeahead(onQuery: (query: string) => void): TypeaheadHandler {
  const query = useRef("");
  const timer = useRef<ReturnType<typeof setTimeout>>(undefined);

  useEffect(() => () => clearTimeout(timer.current), []);

  const reset = useCallback(() => {
    clearTimeout(timer.current);
    query.current = "";
  }, []);

  const handle = useCallback(
    (event: KeyboardEvent): boolean => {
      if (event.nativeEvent.isComposing || MODIFIERS.has(event.key)) return false;
      if (Array.from(event.key).length !== 1 || event.ctrlKey || event.metaKey || event.altKey) {
        reset();
        return false;
      }
      if (event.key === " " && query.current === "") return false;

      query.current += event.key;
      clearTimeout(timer.current);
      timer.current = setTimeout(reset, TYPEAHEAD_TIMEOUT);
      onQuery(query.current);
      return true;
    },
    [onQuery, reset],
  );

  // Both are called by events, never as this renders.
  // oxlint-disable-next-line react/refs
  return useMemo(() => Object.assign((event: KeyboardEvent) => handle(event), { reset }), [handle, reset]);
}