req-092: Destaque de Termos, Sincronização de URL, Debounce, Cache e Navegação via Teclado no Módulo "pages-index"

Descrição do Problema / Contexto

Após validarmos a implementação da req-091, queremos aplicar o mesmo padrão de excelência em usabilidade e desempenho no módulo de listagem final de resultados, o pages-index. Quando o usuário é direcionado para a página de resultados (ou busca diretamente nela), o termo buscado deve ser destacado e a navegação deve se comportar de forma ágil, integrada com a URL e otimizada com cache local.

Mudanças Necessárias (Repositório conn2flow)

1. Destaque Visual (Highlighting) dos Resultados

• Destaque Dinâmico: Ao renderizar os resultados de busca (tanto no carregamento inicial quanto via paginação/busca AJAX assíncrona), o termo buscado deve ser destacado visualmente no título da página ([[item#title]]) e no resumo ([[item#summary]]).

• Implementação: No frontend (pages-index.widget.js), buscar os contêineres de título/resumo em cada item e destacar a correspondência envolvendo o termo buscado em uma tag <mark> (ou tag <span> com estilização visual destacada). O destaque deve ser case-insensitive.

2. Integração Bidirecional com a URL (Parâmetro GET)

• Carregamento Inicial: Se o usuário acessar a página de índice com um parâmetro GET na URL (ex: ?search=termo), o termo deve preencher o input .pages-index-search, a busca correspondente deve ser disparada imediatamente e os termos correspondentes destacados nos itens.

• Sincronização Ativa: Ao digitar no input .pages-index-search, o script JavaScript deve atualizar a URL do navegador em tempo real (usando history.replaceState ou similar) adicionando ou atualizando a variável search=termo. Isso garante que a URL do navegador sempre reflita a busca ativa, permitindo compartilhamento e recarregamento coerentes da página de busca.

3. Melhorias e Sugestões de Usabilidade Aprovadas (Alinhadas com forms-search)

• Navegação via Teclado na Listagem:

  • Se o input .pages-index-search estiver focado e o usuário usar as teclas ArrowDown ou ArrowUp, o foco visual (uma borda ou destaque de hover/seleção) deve percorrer os itens de resultados renderizados na página.

  • Ao pressionar Enter com um item ativo, o navegador deve ser redirecionado para a URL daquele item.

• Debounce Otimizado: Garantir que o debounce de 300ms no evento input do campo de busca previna condições de corrida (race conditions) cancelando chamadas anteriores em andamento (AbortController).

• Cache Local no JavaScript: Implementar cache local em memória JS no widget para que buscas repetidas por termos idênticos ou alternância rápida de páginas com o botão "Carregar mais" sejam recuperadas de forma instantânea sem nova requisição assíncrona ao servidor.

Validação e Testes

1. Verificação de Sintaxe:

   • Executar php -l em todos os novos arquivos PHP gerados nos novos diretórios dos módulos.

   • Executar node --check ou similar nos novos arquivos JavaScript.

2. Testes Unitários:

   • Atualizar a suíte de testes unitários em Vitest para cobrir as novas mecânicas de destaque e navegação por teclado no pages-index.widget.test.js.

   • Rodar composer test no projeto conn2flow para garantir que o backend não tenha regressões.

3. Validação Operacional:

   • Acessar a página de busca passando ?search=termo na URL e verificar se o input carrega o termo, a busca filtra as páginas e os termos são marcados com <mark>.

   • Mudar a busca no input e verificar se a URL é atualizada de forma não-intrusiva com a busca correspondente.