Navegação pelo teclado em listas de sugestões

Anexe o manipulador de teclado ao evento onKeyDown no elemento de entrada, não a onKeyPress (obsoleto) nem a onKeyUp. keyDown é acionado antes que o caractere apareça no campo de entrada, o que permite interceptar ArrowDown, ArrowUp, Enter e Escape antes que tenham qualquer efeito padrão do navegador.

Quando o usuário pressiona ArrowDown, incremente selectedIndex em 1, limitado ao máximo de suggestions.length - 1: setSelectedIndex(prev => Math.min(prev + 1, suggestions.length - 1)). Também chame e.preventDefault() para impedir que o cursor pule para o fim do texto do campo de entrada, que é o comportamento padrão do navegador para ArrowDown em campos de texto.

Quando o usuário pressiona ArrowUp, decremente selectedIndex em 1, limitado ao mínimo de 0: setSelectedIndex(prev => Math.max(prev - 1, 0)). Você também pode limitar o valor a -1 (nenhuma seleção) ao ultrapassar o índice 0, permitindo que o usuário remova a seleção e volte a digitar livremente.

Quando Enter for pressionado e selectedIndex >= 0, selecione a sugestão destacada: defina inputValue como suggestions[selectedIndex], feche a lista suspensa e redefina selectedIndex para -1. Se nenhuma sugestão estiver destacada (selectedIndex for -1), permita que o envio normal do formulário ou a ação de pesquisa continue.

Quando Escape for pressionada, feche a lista suspensa definindo isOpen como false e redefina selectedIndex para -1. Não limpe o valor do campo de entrada — o usuário só quer dispensar as sugestões sem selecionar uma, mantendo o texto digitado para continuar editando.

Quando Tab for pressionada, feche a lista suspensa, pois o navegador moverá o foco para o próximo elemento que possa recebê-lo. Definir isOpen como false ao pressionar Tab garante que a lista suspensa não permaneça aberta depois que o foco sair do campo de entrada. Não é necessário chamar preventDefault() — deixe o navegador cuidar da ordem natural de tabulação.

A sugestão destacada deve ser visualmente distinta. Aplique um estilo ativo à sugestão em selectedIndex: className={index === selectedIndex ? 'suggestion suggestion--active' : 'suggestion'}. O estado ativo normalmente usa uma mudança na cor de fundo, deixando claro qual item será selecionado se Enter for pressionada.

Quando a lista de sugestões tem uma altura máxima e permite rolagem, o item destacado pode sair da tela durante a navegação pelo teclado. Use uma matriz de referências para armazenar os elementos DOM das sugestões e chame listItemRefs.current[selectedIndex]?.scrollIntoView({ block: 'nearest' }) sempre que selectedIndex mudar. O valor de bloco nearest minimiza a quantidade de rolagem.

Quando o campo de entrada mudar e uma nova lista filtrada aparecer, redefina selectedIndex para -1 na mesma atualização de estado ou em um useEffect que dependa das sugestões. Índices desatualizados apontando para itens removidos fariam o usuário selecionar a sugestão errada.

O fluxo completo do usuário é: digitar para filtrar, ArrowDown destacar o primeiro item, mais pressões de ArrowDown percorrerem a lista, ArrowUp voltar na lista, Enter selecionar o item destacado e Escape dispensar as sugestões sem selecionar. Isso abrange todos os padrões comuns de interação pelo teclado esperados pelos usuários de um campo de preenchimento automático.

Sempre chame e.preventDefault() ao tratar ArrowDown e ArrowUp dentro de um campo de texto. Sem isso, ArrowDown move o cursor de texto para o fim, e ArrowUp o move para o início. Esses movimentos do cursor entrariam em conflito com a navegação pelo índice selecionado, criando um comportamento confuso.

O que deve acontecer quando o usuário pressiona Enter com uma sugestão destacada em selectedIndex = 2?

Gerencie onKeyDown na entrada. ArrowDown incrementa selectedIndex (limitado ao máximo), ArrowUp decrementa (limitado a 0 ou -1), a tecla de confirmação seleciona o item destacado, a tecla de escape fecha sem selecionar e a tecla de tabulação fecha e permite que o navegador mova o foco. Sempre chame preventDefault nas teclas de seta e role o item destacado para que fique visível.