# SearchBar
> Componentes / Formulário e ação · Estado: **Em andamento** — Implementado e utilizável, mas ainda sem a validação completa de acessibilidade.
Formulário de busca de um campo só, sobre o Input do sistema: lupa à esquerda, "Limpar busca" quando há texto, `role="search"`, rótulo para o leitor, envio pelo Enter e, se pedido, o botão "Buscar".
- Função: Formulário e ação
- Também chamado de: busca, campo de busca, pesquisa, search
- Mora em: `app/components/molecules/SearchBar.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/SearchBar](https://phorte-design-system.vercel.app/styleguide/peca/SearchBar)
- Ficha no Storybook: [components-complex-searchbar](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-searchbar--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/SearchBar/0](https://phorte-design-system.vercel.app/previa/SearchBar/0)
- Todas as peças: [https://phorte-design-system.vercel.app/llms.txt](https://phorte-design-system.vercel.app/llms.txt)
## Como usar no código
```tsx
import { SearchBar } from '@/app/components/molecules/SearchBar';
…
```
## Uso
### Variantes na ficha
1. [Padrão](https://phorte-design-system.vercel.app/previa/SearchBar/0)
2. [Com Termo](https://phorte-design-system.vercel.app/previa/SearchBar/1)
3. [Interativo](https://phorte-design-system.vercel.app/previa/SearchBar/2)
4. [Com botão](https://phorte-design-system.vercel.app/previa/SearchBar/3)
Para buscar dentro de uma lista ou de um catálogo, quando a busca é o controle principal da área.
### Quando não usar
Para a busca de cursos da página inicial, que exige o tipo de curso, o Hero já traz a dele. Para um campo de texto comum num formulário, o Input.
### Faça
- Dê um `label` que diga o que se busca ("Buscar cursos") — o `placeholder` some quando se digita.
- Trate o `onSubmit`: ele recebe o termo, e o componente já impede o recarregamento da página.
- Use `botaoEnviar` quando quem usa pode não saber que o Enter envia.
- Sem estado no pai, use `defaultValue`: a busca guarda o próprio texto (E60).
### Evite
- Dois SearchBar na mesma página sem nomes diferentes: são duas regiões de busca com o mesmo nome.
### Anatomia
1. **Formulário** — `role="search"`, ocupando a largura disponível.
2. **Lupa** — Ícone decorativo, à esquerda, dentro do campo.
3. **Campo** — O Input do sistema, `type="search"`, com a lupa no encaixe de início.
4. **Limpar busca** — Botão de 44×44 que aparece quando há texto.
5. **Buscar** — Com `botaoEnviar`: Button primário ao lado do campo.
6. **Rótulo** — Só para o leitor de tela (`sr-only`), "Buscar" por padrão.
### Estados
| Estado | O que muda |
| --- | --- |
| Padrão | Borda `--border-interactive`, placeholder em cinza. |
| Foco | Borda `--border-focus` de 2px, por CSS. |
| Com termo | O texto digitado e o botão "Limpar busca" (o X nativo do navegador sai, para não haver dois). |
### Comportamento
| Situação | O que acontece |
| --- | --- |
| Enter | Envia: impede o recarregamento e chama `onSubmit` — medido: a story mostra "Buscou por: gestao". |
| Esc ou "Limpar busca" com termo | Limpa o campo, chama `onLimpar` e deixa o foco no campo — conferido no teste da ficha. |
### Relacionados
- [Input](https://phorte-design-system.vercel.app/styleguide/md/Input.md) — O campo de texto comum.
- [Hero](https://phorte-design-system.vercel.app/styleguide/md/Hero.md) — Traz a busca de cursos da página inicial.
- [CourseFilterSidebar](https://phorte-design-system.vercel.app/styleguide/md/CourseFilterSidebar.md) — Busca com filtros, no catálogo.
## Especificação
### Propriedades
| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `placeholder` | `string` | `'Buscar...'` | não | |
| `value` | `string` | — | não | Valor controlado. Sem ele, a busca guarda o próprio texto (E60). |
| `defaultValue` | `string` | — | não | Valor inicial, no uso não controlado. |
| `onChange` | `(e: React.ChangeEvent) => void` | — | não | |
| `onSubmit` | `(e: React.FormEvent, termo: string) => void` | — | não | Recebe o texto buscado. |
| `onLimpar` | `() => void` | — | não | Chamado ao limpar (botão ou `Esc`). No uso controlado, é aqui que o valor volta a vazio. |
| `label` | `string` | `'Buscar'` | não | Nome acessível do campo. O `placeholder` não serve para isso: some assim que a pessoa começa a digitar, e é justamente aí que ela pode precisar reconferir o que aquele campo é. |
| `botaoEnviar` | `boolean` | `false` | não | Mostra o botão "Buscar" ao lado do campo (E60). Sem ele, envia no Enter. |
Aceita também: `Omit, 'onChange' | 'onSubmit' | 'defaultValue'>`.
### Medidas
| Parte | Valor | Classe |
| --- | --- | --- |
| Altura com texto `text-sm` | 46px (medido) | `py-3` |
| Espaço da lupa | 40px à esquerda | `encaixe `inicio` do Input` |
## Acessibilidade
### Teclado
| Tecla | Faz |
| --- | --- |
| Tab | Leva o foco ao campo; com termo, a próxima parada é "Limpar busca"; com `botaoEnviar`, depois "Buscar". |
| Enter | Envia a busca — medido. |
| Esc | Limpa o termo — medido; o foco fica no campo. |
### Leitor de tela
- `role="search"` faz do formulário um marco de busca: quem usa leitor de tela chega nele pela lista de regiões.
- O nome do campo vem do `label` escondido, não do `placeholder`.
### O que sustenta o estado
Usa os padrões: estatico. Falta ouvir com leitor de tela: estatico.
## Status e recursos
| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/molecules/SearchBar.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-searchbar--docs | Disponível |
| Teste de acessibilidade | axe em `npm run test` | No gate de todo commit |
| Leitor de tela | Passada da E33 | Falta ouvir |
| Design | Figma | Desativado até a Fase 2 |
### Histórico
- `fdd10ff` 2026-09-29 — ESTADO: E109 concluida, roteiro final fechado; proximo o merge na main
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/molecules/SearchBar.tsx