Entrada controlada com lista de sugestões

Um componente de preenchimento automático tem duas partes principais: um campo de texto controlado e uma lista suspensa de sugestões. O campo fica no fluxo normal do documento, e a lista suspensa é posicionada de forma absoluta diretamente abaixo dele. Juntos, eles funcionam como um único componente interativo, embora sejam elementos DOM separados.

Você precisa de quatro variáveis de estado: inputValue (cadeia de caracteres — o que foi digitado), suggestions (lista — itens correspondentes atuais), isOpen (booleano — se a lista suspensa está visível) e selectedIndex (número — qual sugestão está destacada para a navegação pelo teclado; começa em -1 quando nenhuma está selecionada).

Torne o campo de entrada totalmente controlado: value={inputValue} e onChange={e => setInputValue(e.target.value)}. Isso dá ao React controle total sobre o texto exibido. Cada pressionamento de tecla atualiza o estado, o que aciona uma nova renderização com o novo valor. Nunca use um campo de entrada não controlado para preenchimento automático — você precisa ler e definir o valor programaticamente.

Quando as sugestões vêm de uma lista local, filtre a cada renderização com base em inputValue: compare cada item usando item.toLowerCase().includes(inputValue.toLowerCase()). Você pode calcular isso com useMemo se a lista for grande, para evitar recalcular a cada nova renderização. Para listas pequenas, a filtragem direta é suficiente.

Abra a lista suspensa quando inputValue.length > 0 e suggestions.length > 0. Feche-a quando o campo perder o foco, com um pequeno atraso para permitir que os cliques nas sugestões sejam registrados primeiro, quando uma sugestão for selecionada ou quando a tecla Escape for pressionada. Defina isOpen de acordo para controlar a renderização condicional.

O evento onBlur é acionado quando o campo de entrada perde o foco, o que acontece quando o usuário clica em uma sugestão. Se você fechar a lista suspensa imediatamente ao perder o foco, o clique na sugestão nunca será registrado, porque a lista desaparece antes de o clique ser acionado. Use setTimeout(() => setIsOpen(false), 150) para dar tempo de o clique ser registrado.

Posicione a lista suspensa com position: absolute para que ela se sobreponha ao conteúdo abaixo do campo em vez de empurrá-lo para baixo. Defina um z-index alto (100 ou mais) para que ela apareça acima dos outros conteúdos. Defina uma max-height com overflow-y: auto para impedir que a lista fique alta demais quando houver muitos resultados.

Cada item de sugestão deve ter um manipulador onClick: onClick={() => { setInputValue(suggestion); setIsOpen(false); }}. Isso define o campo de entrada como a sugestão selecionada e fecha a lista suspensa. A seleção parece imediata e natural, correspondendo ao comportamento esperado pelos usuários em campos de preenchimento automático.

Uma alternativa ao tempo limite de perda de foco é usar onMouseDown={e => e.preventDefault()} em cada item de sugestão. Isso impede que o pressionamento do botão do mouse roube o foco do campo de entrada, portanto o evento de perda de foco não é acionado ao clicar em uma sugestão. O campo mantém o foco, e o manipulador de clique é executado corretamente.

Um bom preenchimento automático deve ser navegável pelo teclado. O usuário deve poder pressionar ArrowDown para destacar a primeira sugestão, continuar pressionando essa tecla para avançar pela lista, pressionar Enter para selecionar e pressionar Escape para fechar sem selecionar. Isso é implementado tratando onKeyDown no elemento de entrada.

Sempre que o usuário digitar e inputValue mudar, redefina selectedIndex para -1. Isso remove qualquer seleção anterior pelo teclado, para que o novo conjunto de sugestões filtradas comece sem nenhum item destacado. Um índice de seleção desatualizado apontando para um item diferente depois que a lista muda é confuso e incorreto.

Por que usar onMouseDown com e.preventDefault() nos itens de sugestão em vez de depender de um tempo limite de perda de foco?

Um componente de preenchimento automático precisa de quatro variáveis de estado: inputValue, sugestões, isOpen e selectedIndex. Use um campo de entrada controlado, filtre as sugestões com base no campo de entrada e gerencie a visibilidade da lista suspensa por meio de isOpen. Trate a condição de corrida entre perda de foco e clique usando um tempo limite ou preventDefault em onMouseDown. Redefina selectedIndex sempre que o campo de entrada mudar.