# Highlight

Marca, dentro de um texto, o trecho que a pessoa buscou. É o que faz a lista de
resultados dizer **por que** cada linha apareceu: quem digitou "sao" vê o "São"
de "São José dos Campos" pintado.

```tsx
const [query, setQuery] = useState('')
const found = cities.filter((name) => matchesSearch(name, query))

<SearchInput aria-label="Buscar cidade de entrega" value={query} onChange={(event) => setQuery(event.currentTarget.value)} />
{found.map((name) => (
  <Highlight key={name} query={query}>{name}</Highlight>
))}
```

O texto entra como filho, e tem que ser `string`: o destaque é calculado sobre
ele. `query` é o termo, ou uma lista de termos.

## Sem acento importar

Caixa e acento não importam, nos dois sentidos: "sao" acha "São", "JOÃO" acha
"joao", e "acao" acha "Ação". O que sai pintado é sempre o texto **original**,
com o acento que ele tinha. Acento escrito em duas partes (a letra e o sinal
separados, como sai de alguns bancos) fica dentro do destaque, e não solto
depois dele.

`matchesSearch(texto, termo)` é a mesma regra, para filtrar a lista antes de
destacar: o que o filtro acha é o que o `Highlight` pinta.

## Vários termos

Com uma lista, cada termo é destacado onde aparecer. Dois termos que se
encostam ou se sobrepõem viram um trecho só, e termo vazio ou só de espaço é
ignorado: `query=""` devolve o texto inteiro, sem marca nenhuma.

```tsx
<Highlight query={['pedido', 'cancelado']}>
  O pedido 1042 foi cancelado dentro do prazo.
</Highlight>
```

## A cor

Cada trecho sai num `<mark>` com o fundo cheio `warning`, a tinta
`warning-fg` e peso semibold. São dois pares medidos em `src/lib/contrast.ts`,
nos dois temas: o fundo contra os três fundos da casa (`bg`, `surface` e
`surface-raised`) passa dos 3:1, então o trecho se destaca pela cor e não só
pelo peso; e a tinta sobre o fundo passa dos 4,5:1. O fundo sutil
`warning-subtle` foi descartado por isso: ele media 1,14:1 contra o fundo no
claro e 1,27:1 no escuro, e o destaque vivia só do negrito. A tinta do trecho
não segue o parágrafo em volta, nem quando ele é `fg-muted`.

O `<mark>` não é anunciado pela maioria dos leitores de tela, e não precisa:
quem ouve já sabe o que buscou.

## Partes

O `className` vai no `<span>` de fora. `classNames.mark` alcança cada trecho
achado.

## Quando não usar

- **Texto com ênfase que não vem de busca** é `<strong>` dentro do `Text`. O
  `Highlight` diz "foi isto que você procurou", e usado como ênfase ele engana.
- **Cortar texto longo** é `Text` com `truncate` ou `lineClamp`, e mostrar
  mais sob demanda é `Spoiler`. O `Highlight` não mexe no tamanho do texto.
- **Marcar o item atual de uma lista** é o `aria-selected` da própria lista
  (`Select`, `Combobox`, `Command`). O destaque de busca é outra coisa, e pinta
  por cima do selecionado.

## No React Native

Traduz, sobre o `Text` do pacote, com o mesmo `query` e a mesma regra sem acento. Cada trecho achado é um `Text` aninhado com o mesmo fundo cheio `warning`, a tinta `warning-fg` e o peso semibold, e o de fora aceita todas as props do `Text` (`size`, `tone`, `weight`, `lineClamp`).

A classe de cada trecho vai em `classNames.mark`, como no web. O `matchesSearch` também sai do pacote nativo, para o filtro e o destaque usarem a mesma regra.

## Importação

```tsx
import { Highlight } from '@rivocode/ui'
```

## Exemplos

### A busca que marca o que achou

```tsx
import { Highlight, SearchInput, matchesSearch } from '@rivocode/ui'
import { useState } from 'react'

const CITIES = [
  'São José dos Campos',
  'Ribeirão Preto',
  'Florianópolis',
  'Maceió',
  'São Luís',
  'Juiz de Fora',
]

export function Search() {
  const [query, setQuery] = useState('sao')
  const found = CITIES.filter((name) => matchesSearch(name, query))

  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <SearchInput
        aria-label="Buscar cidade de entrega"
        value={query}
        onChange={(event) => setQuery(event.currentTarget.value)}
        onClear={() => setQuery('')}
      />
      <ul className="flex flex-col gap-1 text-base text-fg">
        {found.map((name) => (
          <li key={name}>
            <Highlight query={query}>{name}</Highlight>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Vários termos num parágrafo

```tsx
import { Highlight, SearchInput, matchesSearch } from '@rivocode/ui'
import { useState } from 'react'

export function ManyTerms() {
  return (
    <p className="max-w-prose text-base text-fg-muted">
      <Highlight query={['pedido', 'cancelado']}>
        O pedido 1042 foi cancelado dentro do prazo. O pedido 1043 segue de pé, e o estorno
        do primeiro já aparece no extrato.
      </Highlight>
    </p>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `query` | `string \| readonly string[]` | sim |  | - | O termo buscado, ou uma lista deles. |
| `classNames` | `Partial<Record<"mark", string>>` |  |  | - | Classe por parte: `mark`, cada trecho achado. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Heading](/componentes/heading.md)
- [Link](/componentes/link.md)
- [RichTextView](/componentes/rich-text-view.md)
- [Text](/componentes/text.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
