# Text

Parágrafo ou trecho de texto, vestido com os papéis da casa: `size` na escala
de `xs` a `lg`, `tone` entre os papéis de texto do tema, e `weight`.

```tsx
<Text size="sm" tone="muted">Atualizado há 2 minutos.</Text>
```

Sai num `<p>`. O `render` troca o elemento sem mudar o desenho:
`render={<span />}` para o trecho dentro de uma frase, `render={<div />}` para
o bloco que contém outro bloco, que um `<p>` não pode conter.

**Sem `size`, sem `tone` e sem `weight`, o texto herda de quem o cerca.** É o
que faz o trecho funcionar: um valor em negrito dentro de uma frase `sm` fica
`sm`, e fica da cor da frase se não pedir outra. O custo é que o parágrafo
solto também herda, e o corpo da página é o do seu app; passe `size` no
parágrafo de fora.

Os tons são os papéis de texto do tema, e só eles: `neutral` é o texto
corrido, `muted` o secundário, `subtle` a legenda, `accent` o destaque da
marca, e `success`, `warning`, `danger` e `info` são os `-text` de cada
estado, os que se leem sobre o fundo da página. Os de preenchimento
(`bg-danger` e parentes) não entram, porque não têm contraste como texto.

`truncate` corta em uma linha, e `lineClamp` corta depois de 1 a 6 linhas;
quando os dois vêm, `lineClamp` vence. O texto cortado continua inteiro no
DOM: o leitor de tela ouve tudo, e quem vê precisa de um `title` ou de um
`Tooltip` para ler o resto.

## Quando não usar

- **Nome de arquivo, comando ou chave de JSON no meio da frase:** `Code`. Ele
  muda a letra para a de largura fixa e marca o trecho como código; um `Text`
  com `font-mono` parece igual e não diz o que é.
- **Uma tecla ou um atalho:** `Kbd`. Ele desenha a tecla e diz o nome dela a
  quem ouve a tela; `Text` em negrito escrito "Ctrl+K" não faz nenhuma das
  duas coisas.
- **Título de seção:** `Heading`. Texto grande não entra no esboço da página,
  e quem navega por título não o encontra.
- **Rótulo de campo:** `FieldLabel`, que se liga ao controle.

## No React Native

Traduz, e o `Text` nativo é o mesmo primitivo que as outras peças do pacote já vestem, agora com `size`, `tone`, `weight`, `truncate` e `lineClamp`, os mesmos nomes e os mesmos valores do web. `truncate` e `lineClamp` viram `numberOfLines`.

**Sem as props novas, o aninhado herda, como no web.** Um `Text` dentro de outro `Text` leva o corpo e a cor do de fora, e é isso que faz o trecho em negrito no meio da frase funcionar. A diferença está no topo: o React Native não herda cor de `View`, então o `Text` de fora sem `tone` sai em `text-fg`, a cor de texto do tema - a mesma do `tone="neutral"` -, e não na cor padrão do aparelho, que era preto no tema escuro. A cor que vem em `className` ou em `style` vence esse padrão.

Não há `render`: o elemento do celular é sempre `Text`, e o bloco é uma `View` em volta.

## Importação

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

## Exemplos

### Os tons

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

export function Tones() {
  return (
    <div className="flex flex-col gap-1">
      <Text size="base" tone="neutral">
        Texto corrido, no tom neutro.
      </Text>
      <Text size="base" tone="muted">
        Texto secundário, que explica o de cima.
      </Text>
      <Text size="sm" tone="subtle">
        Legenda, atualizada há 2 minutos.
      </Text>
      <Text size="sm" tone="success">
        Pagamento aprovado.
      </Text>
      <Text size="sm" tone="warning">
        Assinatura vence em 5 dias.
      </Text>
      <Text size="sm" tone="danger">
        Pagamento recusado.
      </Text>
      <Text size="sm" tone="info">
        Nova versão do aplicativo disponível.
      </Text>
    </div>
  )
}
```

### Trecho dentro da frase

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

export function Inline() {
  return (
    <Text size="base" tone="muted" className="max-w-96">
      O total do mês foi{' '}
      <Text render={<span />} tone="neutral" weight="semibold">
        R$ 48.310,00
      </Text>
      , e o trecho herda o corpo da frase.
    </Text>
  )
}
```

### Cortar o que não cabe

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

const MOTIVO =
  'Recusado pela transportadora por divergência no CEP informado no pedido, e devolvido ao estoque depois de duas tentativas de entrega no mesmo dia.'

export function Clamp() {
  return (
    <div className="flex w-72 flex-col gap-3">
      <Text size="sm" truncate>
        {MOTIVO}
      </Text>
      <Text size="sm" tone="muted" lineClamp={2}>
        {MOTIVO}
      </Text>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `lineClamp` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  |  | - | Corta depois de tantas linhas, de 1 a 6, com reticencias na ultima. |
| `ref` | `Ref<HTMLParagraphElement>` |  |  | - |  |
| `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |  | - | Troca o elemento mantendo a aparencia: `<Text render={<span />}>` para o trecho dentro de uma frase, `<Text render={<div />}>` para o bloco que contem outro bloco. |
| `size` | `TextSize` |  |  | - | O corpo na escala da casa, de `xs` (12px) a `lg` (18px); acima disso e titulo, e o titulo e o `Heading`. |
| `tone` | `TextTone` |  |  | - | O papel de cor: `neutral` e o texto corrido, `muted` o secundario, `subtle` a legenda, e os tons de estado sao os `-text`, os que se leem sobre o fundo da pagina. |
| `truncate` | `boolean` |  |  | - | Corta em uma linha com reticencias. |
| `weight` | `TextWeight` |  |  | - | O peso da letra, lido dos tokens de peso do tema: `regular` e `--rc-weight-regular`, `medium` e `--rc-weight-medium`, `semibold` e `--rc-weight-strong` e `bold` e `--rc-weight-bold`. |

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

## Ver também

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