BaseSearch

Campo de busca para filtrar uma lista ou tabela enquanto a pessoa digita. Tem lupa, botão para limpar e, opcionalmente, o atalho / para chegar ao campo de qualquer ponto da tela.

Buscar contratos

v-model (após 300 ms sem digitar): "" · último Enter: ""

Uso

• Use para filtrar o que já está na tela: contratos, itens da planilha, obras no mapa.
• O label é obrigatório e fica só para o leitor de tela. Diga o que é buscado: "Buscar contratos", não "Buscar". Dentro de um BaseField, o rótulo do BaseField dá o nome e o label pode ficar de fora.
• O placeholder mostra por onde se pode buscar: "Buscar por contrato, obra ou empresa". Ele não substitui o label.
• O v-model atualiza depois de debounce ms sem digitar (300 por padrão), para a lista não piscar a cada tecla. Enter e limpar atualizam na hora.
• Para busca no servidor, ouça o evento search (Enter) ou o v-model, e ligue loading enquanto a resposta não chega.
• Não use para escolher um valor de uma lista fechada: use um seletor.
• A busca do cabeçalho do protótipo, clara sobre o azul da marca, ainda não tem variante aqui: o BaseSearch é desenhado para fundo claro ou escuro de página.

Anatomia

1. Rótulo: escondido na tela e lido pelo leitor de tela, vindo de label.
2. Ícone de lupa: no começo do campo, sempre presente.
3. Campo: onde a pessoa digita, com o exemplo de placeholder enquanto está vazio.
4. Fim do campo: o indicador de loading, o botão "Limpar busca" quando há texto e a dica da tecla / com shortcut e o campo vazio.

Atalho de teclado

Buscar em todo o sistema

/

Atalho: tecla /

Com shortcut, a tecla / leva o foco ao campo quando o foco não está em outro campo de texto nem dentro de um modal aberto. Ligue em uma busca só por página, normalmente a do cabeçalho. A dica some quando há texto ou quando o campo está em foco.

Estados

Com texto

Carregando

Buscando

Inválido

Somente leitura

Desabilitado

invalid só marca a borda. Para dizer o que corrigir, coloque o campo num BaseField com invalid-text: a mensagem aparece com ícone e o leitor de tela a ouve junto com o campo.

Buscar por número

Use só letras, números e a barra, como em 012/2026.

Sem BaseField, ligue a mensagem pelo aria-describedby, que vai para o <input>: <BaseSearch invalid aria-describedby="search-error" />.

Tamanhos

Pequeno

Médio

Grande

Faça e não faça

Faça	Não faça
Dê o rótulo "Buscar contratos"	Usar só "Buscar", sem dizer o que se busca
Ligue loading enquanto o servidor responde e anuncie o total encontrado	Deixar a lista mudar sem aviso ao leitor de tela
Use um seletor para escolher uma comarca de uma lista fechada	Usar a busca para escolher um valor de uma lista fechada

Estilo

O campo é o BaseInput; veja BaseField e BaseInput para fundo, borda e estados.

Propriedade	Token
Lupa	--tj-icon-secondary, --tj-icon-sm
Botão limpar	--tj-text-helper; hover --tj-icon-primary sobre --tj-layer-accent-01; pressionado --tj-layer-accent-02; foco contorno de 2 px --tj-border-interactive com --tj-ring
Tamanho do botão limpar	altura do campo menos --tj-space-2 (24, 32 e 40 px)
Dica do atalho	--tj-text-helper sobre --tj-layer-accent-01, borda --tj-border-subtle-02, --tj-text-xs, --tj-radius-sm
Carregando	anel --tj-border-subtle-02 com --tj-interactive, --tj-icon-sm
Altura	--tj-control-sm/md/lg
Movimento	--tj-duration-fast-02, --tj-easing-standard

Código

<BaseSearch
  v-model="query"
  label="Buscar contratos"
  placeholder="Buscar por contrato, obra ou empresa"
  :loading="loading"
  shortcut
  @search="searchOnServer"
/>

Propriedades

Propriedade	Tipo	Padrão	Descrição
label	string	—	Nome do campo para o leitor de tela; obrigatório fora de um BaseField
size	'sm' | 'md' | 'lg'	'md'	Altura
placeholder	string	—	Exemplo do que se pode buscar
disabled	boolean	false	Desabilita o campo
readonly	boolean	false	Mostra o termo sem permitir mudança
invalid	boolean	false	Marca o erro; dentro de um BaseField, vale também o do campo. Sem BaseField, ligue a mensagem do erro por aria-describedby
loading	boolean	false	Mostra o indicador e anuncia "Buscando"
debounce	number	300	Milissegundos sem digitar antes de atualizar o v-model; 0 atualiza a cada tecla
shortcut	boolean	false	Liga o atalho / e a dica
landmark	boolean	false	Envolve o campo num marco de busca (role="search")
v-model	string	''	Termo buscado, atualizado com atraso enquanto se digita

Os outros atributos vão para o <input>: name, aria-controls (o id da lista ou tabela filtrada), aria-describedby (somado à ajuda do BaseField e à dica do atalho), required e autocomplete, que é off por padrão para o histórico do navegador não cobrir o botão limpar. class e style ficam no elemento de fora.

Evento	Carga	Quando
update:modelValue	string	Depois do debounce, no Enter e ao limpar
search	string	No Enter, com o termo atual; ao limpar, com ''

Acessibilidade

• Com landmark, segue o padrão de marcos (landmarks) do WAI-ARIA APG, no marco de busca.
• É um <input type="search"> com <label for> escondido visualmente. Com landmark, segue o marco de busca (search landmark) do WAI-ARIA APG: o conjunto vira role="search" com o mesmo nome, para quem navega por marcos. Use landmark só na busca principal da página.
• Teclado: Tab chega no campo e depois no botão limpar; Enter busca na hora; Esc limpa. Com o campo já vazio, Esc segue para o componente pai, então um modal ainda fecha.

Tecla	O que faz
Tab / Shift + Tab	Chega no campo e depois no botão "Limpar busca", quando ele aparece
Letras e números	Escrevem no campo; o v-model atualiza depois de debounce ms sem digitar
Enter	Busca na hora: atualiza o v-model e emite search
Esc	Com texto, limpa o campo. Com o campo vazio, segue para o componente em volta, como um modal
/	Com shortcut, leva o foco ao campo de qualquer lugar da página, menos de outro campo ou de dentro de um modal aberto
Enter ou Espaço no botão limpar	Limpa o campo e devolve o foco a ele

• O botão limpar se chama "Limpar busca", aparece só quando há texto e devolve o foco ao campo. O botão nativo do navegador fica escondido para não aparecer duas vezes.
• O atalho / não dispara com Ctrl, Alt ou ⌘, nem quando o foco está em outro campo. AltGr vale, porque é com ele que se digita a barra em teclados ABNT2 sem a tecla /. Com um modal aberto, o foco fica no modal. O campo leva aria-keyshortcuts="/" e o leitor de tela ouve "Atalho: tecla /" junto com ele; a dica visual é decorativa. Com o campo desabilitado, o atalho, a dica e a descrição saem.
• Atalho de uma tecla só (WCAG 2.1.4): ofereça um jeito de desligar, por exemplo uma preferência do usuário ligada à propriedade shortcut.
• loading anuncia "Buscando" numa região role="status" que existe desde o início, para o anúncio não se perder. O indicador gira mais devagar com prefers-reduced-motion.
• Ao terminar a busca, anuncie o resultado (ex.: "12 contratos encontrados") numa região role="status" perto da lista; o BaseSearch só anuncia "Buscando".
• No estado inválido a borda vermelha não basta: use a mensagem do BaseField (texto e ícone), que o campo liga pelo aria-describedby e marca com aria-invalid="true".
• O botão limpar mostra o foco com contorno sólido, e no modo de alto contraste do Windows usa as cores do sistema.
• Funciona nos temas claro e escuro; todas as cores vêm de tokens de papel.
• Testado com axe nos estados padrão, com texto, atalho (vazio, com texto, com marco), desabilitado, somente leitura, inválido, carregando (com e sem texto), tamanhos, dentro de um BaseField e com foco ao começar a carregar.