# Construir tela nativa com o ui-native

O `@rivocode/ui-native` fala o **mesmo vocabulário** do web (`bg-bg`,
`text-fg-muted`, `rounded-pill`) pelo NativeWind, sobre um `theme.css` gerado
dos mesmos tokens. Nenhuma peça conhece a cor da marca aqui também.

Este arquivo é o que muda no celular. Dois outros são consulta, e se abrem pela
peça:

- [native-assinatura.md](native-assinatura.md): o que muda na chamada de cada
  peça, prop a prop, ao reescrever a tela do web;
- [native-paridade.md](native-paridade.md): se a peça existe no nativo, com que
  nome, e o que usar quando ela não existe.

## Conteúdo

- Começar: o app novo em um comando
- Tema: os dois de casa trocam em runtime, o do cliente é build
- Mesmo nome não é mesma API
- O toque muda a tela: as regras de UI/UX no celular
- A navegação do app fica à vista
- Permissão, no momento em que ela faz sentido
- O formulário entra por outro caminho
- Ícone: sempre do lucide-react-native
- O gráfico também, pelo peso
- Copiar e anexar: dois caminhos, e não um
- O campo sai do dado, como no web
- O teclado já vem tratado
- O que nunca fazer no nativo

## Começar: o app novo em um comando

Num app Expo, instale os peers e o pacote como manda
<https://ds.rivocode.com.br/react-native.md>, e rode:

```sh
npx rivocode-ui-native-init
```

Ele escreve a receita inteira (PostCSS, metro, `global.css`, `app.json`,
`browserslist`), confere os peers obrigatórios e imprime o que fez; arquivo que
já existe com outro conteúdo não é reescrito sem `--force`. Siga a linha de
instalação da página ao pé da letra: as tags dos peers (`nativewind@preview`,
`react-native-css@rc`) não são enfeite, e sem elas o npm instala a linha errada
sem avisar. Não escreva um `babel.config.js`: o certo é não existir.

O CSS do app é pré-compilado. Classe nova numa tela pede rodar de novo o
`npx rivocode-ui-native-css`.

## Tema: os dois de casa trocam em runtime, o do cliente é build

`theme="rivocode-dark" | "rivocode-light" | "system"` troca a tela inteira em
runtime, porque essas cores foram compiladas como `light-dark()` e o provider só
gira o `Appearance`. **Tema de cliente não funciona assim.**

**Um `RivoProvider` só, na raiz.** O esquema do `Appearance` é um para o app
inteiro, então não há `scope="local"` como no web: o provider aninhado herda o
tema, o contexto e o `useToast` do de fora, não pinta outro fundo, e só troca as
famílias quando recebe `fonts`. O `theme` passado a ele é ignorado (com aviso em
`__DEV__`); não repita `theme="system"` no aninhado para contornar nada.

- **A cor de classe só muda em BUILD.** O compilador do `react-native-css` crava
  o valor dentro da regra (`.bg-accent` vira `{"backgroundColor":"#d4f34a"}`).
  Nenhum objeto passado em runtime troca cor de classe, e a prop `theme` aceita
  só os três nomes acima.
- **O teto é de dois temas por build.** `light-dark()` tem duas vagas. Um
  cliente por app cabe; cinco temas pedem cinco bundles.

O caminho que funciona: sobrescrever os papéis num `@theme` do `global.css` do
app, depois do `@rivocode/ui-native/theme.css`, e pré-compilar de novo.

```css
@import "@rivocode/ui-native/theme.css";
@import "tailwindcss/utilities.css";

@theme {
  --color-accent: #2563eb;
  --color-accent-fg: #ffffff;
  --color-bg: light-dark(#f7f8fa, #0d1220);
  /* …e os outros papéis que a marca troca. */
}
```

Isto sozinho veste a tela inteira, gráfico incluído: o provider lê os papéis do
mesmo CSS compilado, então a peça que pinta por JS e a que pinta por classe
dizem sempre a mesma cor. O gerador `rivocode-ui-native-theme` deriva os papéis
a partir de oito sementes, e o `@rivocode/ui-native/contrast` mede o resultado
(`checkThemeMap`, `contrastRatio`, `compose`).

<details>
<summary>Versões antigas: o mapa de tema na prop</summary>

Em versões antigas o provider aceitava um objeto de tema na prop `theme` e uma prop
`scheme`. O mapa alcançava só quem lê cor por JS (`ChartDonut`, o giro do
`Spinner`, o trilho do `Switch`), e a tela saía misturada: donut de um tema e
botão de outro. As duas props saíram. Quem migra de lá troca o objeto pelo
`@theme` acima.

</details>

## Mesmo nome não é mesma API

Onde o nome da peça é o mesmo, o nome da prop também é (`Avatar fallback`,
`OTPField onValueComplete`, `ToggleGroup multiple`). **A assinatura, não.**
Nenhuma peça aceita o mesmo JSX dos dois lados, por três regras:

- **No nativo tudo é controlado**: sem `defaultValue`, `defaultChecked`,
  `defaultOpen`. `<Checkbox checked={x} onCheckedChange={setX}>ISS retido</Checkbox>`,
  as duas obrigatórias. A exceção é o que abre e fecha no lugar, `Accordion` e
  `Collapsible`: aceitam os dois modos.
- **A lista vem por `items`, não por composição**: `RadioGroup`,
  `CheckboxGroup`, `ToggleGroup`, `Combobox`, `Tabs` e `Select` recebem o
  array e desenham a folha: `<Select items={…} value onValueChange label />`,
  sem `SelectTrigger`/`SelectContent`/`SelectItem`. A exceção é escolher pelo
  desenho: `RadioCard` e `CheckboxCard` são peças soltas, controladas por
  `checked` e `onCheckedChange`, com `media` para a imagem grande em cima do
  texto - o `icon` do `ToggleGroup` e o do cartão cabem em 20pt e não servem
  para isso.
- **O nome falado é `label`, sempre**, no lugar do `aria-label` do web: o
  `Select`, o `Slider`, o `IconButton`, o `Checkbox` e o `Switch` sem texto ao
  lado, o `OTPField`, o `SignaturePad`. O `accessibilityLabel` só aparece onde
  a peça É o `TextInput` da plataforma (`Input`, `Textarea`, `CurrencyInput`,
  `PasswordInput`) e no `Item`.

Nunca prometa que a tela do web "vai rodar no celular": o que se reaproveita é
o vocabulário de classes, o token e a escolha da peça. O JSX se reescreve, e a
linha de cada peça em [native-assinatura.md](native-assinatura.md) diz como.

**A parte se veste pelo mesmo nome do web.** `className` veste a raiz, e a peça
nativa que aceita `classNames` usa as chaves da seção "Partes" da página web:
`<Banner classNames={{ title: 'font-rc-strong' }} />` se escreve igual nos dois
pacotes. Dois limites, os dois do React Native:

- **Parte que o nativo não desenha fica fora do tipo**: o `pause` do
  `Carousel`, o `code` do `QRCode`. Cada uma tem linha na tabela de assinatura.
- **Cor de texto não desce de `View` para `Text`.** Numa parte que é caixa (o
  `trigger` do `Spoiler`, o `footer` do `Carousel`), `text-*` não pinta o
  texto de dentro; vista a parte que é o próprio `Text`.

Não há prop `<parte>ClassName`: a parte se veste só pelo `classNames`. A
exceção é o `contentContainerClassName` do `ScrollArea`, que é o nome que a
`ScrollView` já dá ao conteúdo que rola.

## O toque muda a tela: as regras de UI/UX no celular

As regras do `SKILL.md` valem aqui inteiras: placeholder em todo campo, os
quatro momentos de toda ação, uma ação primária por área. O que o dedo muda:

- **Alvo de 44pt.** É o mínimo do iOS (o Android pede 48dp). As peças já
  nascem nessa altura, e por isso o nativo não tem `density`; o que você monta
  à mão com `Pressable` leva `min-h-11`, e ícone sozinho é `IconButton`. Ícone
  com texto é o `icon` do `Button` (ou do item de `Tabs` e `ToggleGroup`), pela
  função que recebe a cor: `icon={({ color, size }) => <Plus color={color}
  size={size} />}`. A ação destrutiva que não é a principal é
  `variant="ghost" tone="danger"` (o `tone` só vale no `ghost`), e não um
  `danger` cheio no rodapé.
- **A ação principal mora embaixo, ao alcance do polegar.** Em tela com
  formulário, no `footer` da `ScrollArea`, que sobe com o teclado. Em lista com
  seleção, na `ActionBar`.
- **Escolher abre folha.** `Select`, `Combobox`, `DatePicker` e `Menu` já abrem
  em `Sheet`; detalhe de item, filtro e ação secundária também vão em `Sheet`,
  e não em página nova.
- **Sem hover, sem dica.** O `Tooltip` não porta: o que a dica dizia vai para a
  tela, num `Text tone="muted"` ou na `description` do `Field`.
- **O teclado certo é parte do campo.** `MaskedInput` já abre o numérico e o
  `phone-pad`; e-mail leva `keyboardType="email-address"` e
  `autoCapitalize="none"`.

```tsx
<ScrollArea
  contentContainerClassName="gap-4 p-5"
  footer={
    <Button loading={emitting} onPress={emit}>
      Emitir nota
    </Button>
  }
>
  <Field label="Cliente">
    <Input value={customer} onChangeText={setCustomer} placeholder="Ex.: Clínica São Lucas" />
  </Field>
  <Field label="E-mail para a nota" description="O PDF chega neste endereço.">
    <Input
      value={email}
      onChangeText={setEmail}
      placeholder="nome@empresa.com.br"
      keyboardType="email-address"
      autoCapitalize="none"
      autoComplete="email"
    />
  </Field>
</ScrollArea>
```

Lista de consulta é `DataList` (que recebe `isLoading`, `isError` com
`onRetry`, `empty`, `isFetching` e `isRefetchError`, como o `DataTable`) ou
`QueryBoundary` em volta do que você desenhar. O `DataList` é uma `FlatList`:
`onRefresh` e `refreshing` ligam o puxar para atualizar, que continua valendo
com a lista vazia (o `empty` vai dentro da `FlatList`), e dentro de uma
`ScrollView` (como a de cima) ele leva `scrollEnabled={false}`. O `className`
do `DataList` veste a raiz em todo final, o erro inclusive. O `QueryBoundary`
com `isFetching` embrulha os filhos numa caixa `flex-1`, então a `ScrollArea`
`flex-1` de dentro ocupa a tela sem `classNames` nenhum. Lista longa com
título ou busca em cima não pede `FlatList` à mão: `header` rola junto, e
`stickyHeaderIndices={[0]}` o prende. O aviso de "deu certo" é o `useToast`, com `title` e
`description`, e o "Desfazer" de uma exclusão vai no próprio aviso, pelo mesmo
`actionProps` do web com `onPress` no lugar do `onClick`:
`actionProps: { children: 'Desfazer', onPress: restore }`. Só o aviso com botão
recebe toque.

## A navegação do app fica à vista

O esqueleto do app é do router, e a decisão é sua:

- **Até cinco destinos principais vão numa tab bar**, cada um com ícone e
  rótulo escrito. Ícone sem rótulo obriga a decorar, e o leitor de tela fala
  só o nome que você der.
- **O drawer é para o que sobra**, e nunca para a navegação principal: o
  escondido é menos achado e mais lento.
- **Mais de cinco** é sinal de rever a arquitetura antes de inventar uma
  aba "Mais".
- A primeira aba é o início, e tocar na aba ativa volta ao topo dela.

**A barra de abas e o cabeçalho saem iguais no iPhone e no Android.** O
`NativeTabs` e o cabeçalho da pilha nativa são desenhados pelo sistema: Liquid
Glass num, Material no outro, título grande só no iOS, chevron de um lado e
seta do outro. Para o desenho igual, use as `Tabs` do expo-router, que são
desenhadas em JS, com a `tabBar` montada com peças da casa e os ícones do
`lucide-react-native`, e o cabeçalho da `Stack` pelo `header`, com o
`PageHeader`. A `Stack` continua sendo a pilha nativa (o gesto e a troca de
tela seguem no sistema); só o desenho do cabeçalho passa a ser seu. Não use
`headerLargeTitle`: ele só existe no iOS.

```tsx
import { Pressable, View } from 'react-native'
import { Stack as RouterStack, Tabs as RouterTabs } from 'expo-router'
import type { BottomTabBarProps } from '@react-navigation/bottom-tabs'
import type { NativeStackHeaderProps } from '@react-navigation/native-stack'
import { useSafeAreaInsets } from 'react-native-safe-area-context'
import { ChevronLeft, House, Package, UserRound, type LucideIcon } from 'lucide-react-native'
import { IconButton, PageHeader, Text, useRivo } from '@rivocode/ui-native'

const ICONES: Record<string, LucideIcon> = { index: House, pedidos: Package, conta: UserRound }

function BarraDeAbas({ state, descriptors, navigation }: BottomTabBarProps) {
  const { colors } = useRivo()
  const { bottom } = useSafeAreaInsets()
  return (
    <View className="flex-row border-t border-border bg-bg" style={{ paddingBottom: bottom }}>
      {state.routes.map((route, index) => {
        const ativa = state.index === index
        const Icone = ICONES[route.name] ?? House
        const rotulo = descriptors[route.key]?.options.title ?? route.name
        const tocar = () => {
          const evento = navigation.emit({ type: 'tabPress', target: route.key, canPreventDefault: true })
          if (!ativa && !evento.defaultPrevented) navigation.navigate(route.name)
        }
        return (
          <Pressable
            key={route.key}
            onPress={tocar}
            accessibilityRole="tab"
            accessibilityState={{ selected: ativa }}
            className="min-h-11 flex-1 items-center justify-center gap-0.5 py-2"
          >
            <Icone color={ativa ? colors['accent-text'] : colors['fg-muted']} size={22} />
            <Text size="xs" tone={ativa ? 'accent' : 'muted'}>{rotulo}</Text>
          </Pressable>
        )
      })}
    </View>
  )
}

export function AbasDoApp() {
  return (
    <RouterTabs tabBar={(props) => <BarraDeAbas {...props} />} screenOptions={{ headerShown: false }}>
      <RouterTabs.Screen name="index" options={{ title: 'Início' }} />
      <RouterTabs.Screen name="pedidos" options={{ title: 'Pedidos' }} />
      <RouterTabs.Screen name="conta" options={{ title: 'Conta' }} />
    </RouterTabs>
  )
}

function Cabecalho({ options, route, back, navigation }: NativeStackHeaderProps) {
  const { top } = useSafeAreaInsets()
  return (
    <View className="flex-row items-center gap-1 border-b border-border bg-bg px-2 pb-2" style={{ paddingTop: top }}>
      {back && (
        <IconButton label="Voltar" variant="ghost" onPress={navigation.goBack}>
          {({ color, size }) => <ChevronLeft color={color} size={size} />}
        </IconButton>
      )}
      <PageHeader title={options.title ?? route.name} className="flex-1 px-2" />
    </View>
  )
}

export function PilhaDePedidos() {
  return <RouterStack screenOptions={{ header: (props) => <Cabecalho {...props} /> }} />
}
```

O `Tabs` e a `Stack` do expo-router entram com outro nome porque o pacote tem
os seus: o `Tabs` da casa é a caixinha segmentada, e a `Stack` é a pilha de
layout com `gap`, e os dois costumam morar no mesmo arquivo. O `tabPress`
emitido é o que faz o toque na aba ativa voltar ao topo, nas telas que usam o
`useScrollToTop`.

**`NativeTabs` e cabeçalho nativo, só por escolha consciente.** Quem quer o
desenho do sistema aceita que ele não sai igual, e isso vai escrito na tela,
como nas peças: "a barra de abas e o cabeçalho nativos são desenhados pelo
sistema e não saem iguais; para desenho igual, use as `Tabs` do router com
peças da casa". Mesmo assim, o ícone é um só nos dois, da mesma fonte: o `src`
com a imagem gerada do mesmo ícone do lucide, e nunca `sf` de um lado e `md` ou
`drawable` do outro. O `md` (símbolo do Material via `expo-symbols`) ainda
quebrou no Expo Go do SDK 58 com o React Native 0.88.1 ("Cannot read property
'getAssetByID' of undefined", vindo do `expo-asset`).

## Permissão, no momento em que ela faz sentido

Notificação, câmera, localização e contatos se pedem **quando a pessoa toca no
que precisa delas**, e nunca na abertura do app. O pedido do sistema aparece
uma vez só: recusado ali, voltar atrás exige ir aos Ajustes.

1. Antes do pedido do sistema, uma tela ou `Sheet` da casa diz o ganho, com
   duas saídas: "Ativar avisos de entrega" e "Agora não".
2. Só o "Ativar" chama o pedido do sistema.
3. Recusado, a funcionalidade continua usável de outro jeito ("Digite o
   código" no lugar da câmera), e um `Button` leva aos Ajustes.

O texto que o sistema mostra no pedido (no Expo, em `ios.infoPlist` do
`app.json`, ou na opção do plugin do módulo) diz o uso concreto: "A câmera lê o
QR da nota", e não "O app precisa da câmera".

## O formulário entra por outro caminho

`Form`, `FormField`, os adaptadores e o `useZodForm` vivem em
`@rivocode/ui-native/form`, não no índice da raiz: o `react-hook-form` é peer
opcional, e o metro resolve import por arquivo.

Duas diferenças mordem logo. **Nada envia sozinho**: sem `<form>`, sem
`type="submit"`, sem Enter, o `Form` entrega `{ submit, isSubmitting }` por
função, e o `isSubmitting` é o `loading` do botão. **O rótulo viaja no campo**:
o `FormField` põe `accessibilityLabel` e `invalid` na linha, e o adaptador os
leva ao controle (`forText` no `Input`, `forFiles` no `FileUpload`, `forValue` no
resto). O `forValue` leva
o `invalid` só quando há erro, e as peças de hora (`TimeField`, `TimePicker`)
leem o erro do `Field` como as de data: não passe `invalid` à mão no
`FormField`.

**O `Form` não ocupa a altura sozinho.** Ele embrulha os filhos numa coluna com
`gap-5`, sem `flex-1`. Com `ScrollArea` dentro e a `FormSaveBar` presa embaixo,
passe `className="flex-1 gap-0"` ao `Form`: o `flex-1` dá altura à rolagem, e o
espaço entre os campos fica no `contentContainerClassName` da `ScrollArea`.

**O rótulo já vem do `FormField`, não repita.** O `Slider` com `showValue` e o
`Checkbox` com texto em `children` desenham o próprio rótulo; dentro de
`FormField`, que já escreve o rótulo da linha, use o `Slider` sem `showValue`
(ou escreva o valor fora dele) e o `Checkbox` sem `children`, ou a pessoa lê e
ouve o nome duas vezes.

```tsx
import { Form, FormField, forText, useZodForm } from '@rivocode/ui-native/form'

<Form form={form} onSubmit={emit}>
  {({ submit, isSubmitting }) => (
    <>
      <FormField name="customer" label="Cliente">
        {(row) => <Input {...forText(row)} placeholder="Ex.: Clínica São Lucas" />}
      </FormField>
      <Button loading={isSubmitting} onPress={submit}>
        Emitir nota
      </Button>
    </>
  )}
</Form>
```

## Ícone: sempre do lucide-react-native

O `lucide-react-native` e o `react-native-svg` são peers **obrigatórios** da
raiz desde a 6.0, e entram na primeira linha da instalação. Todo ícone da
tela vem dele, com o mesmo nome do web (`Receipt` lá é `Receipt` aqui) - e as
peças da biblioteca fazem o mesmo: o `ChevronDown` do `Select`, o `Check` do
`Checkbox`, o `Star` do `Rating`. Nunca desenhe ícone à mão: nada de `View`
girada fazendo seta ou visto, caractere (`✓`, `›`, `★`, `−`, `×`) ou SVG
próprio. Outro conjunto só entra quando o lucide não tem o desenho.

A cor não desce da `View` para o SVG: o ícone recebe `color` com o papel do
tema, lido de `useRivo().colors`, ou chega pela função das peças que aceitam
ícone, que entregam a cor e o tamanho certos.

```tsx
import { Trash2 } from 'lucide-react-native'

<IconButton label="Excluir pedido" variant="ghost">
  {({ color, size }) => <Trash2 color={color} size={size} />}
</IconButton>
```

## O gráfico também, pelo peso

`ChartContainer`, `ChartDonut`, `ChartRadial`, `ChartGauge`, `ChartHeatmap`,
`ChartFunnel` e `ChartTreemap` vivem em `@rivocode/ui-native/chart` e desenham
com o `react-native-svg`, que já é peer da raiz: a porta própria é pelo peso. O
`QRCode`, o `PixCode` e o `SignaturePad` moram no mesmo caminho. O copiar do `PixCode` entra por `renderCopy`,
com o `Clipboard` de `@rivocode/ui-native/clipboard`. O PNG da assinatura não
porta, porque não há canvas.

```tsx
import { ChartBar, ChartContainer, ChartDonut, ChartLine, ChartRadial, PALETTE, PixCode, QRCode } from '@rivocode/ui-native/chart'
import { SignaturePad, isSignatureEmpty, signatureToSvg } from '@rivocode/ui-native/chart'
```

Três coisas mordem. **A moldura mede e entrega**: `children` como função recebe
`{ width, height, colors }`, no lugar do `ResponsiveContainer` e das
`var(--color-série)`, e a medida chega zerada no primeiro quadro. **No toque
não há dica**: a legenda da rosca é o controle, e tocar a linha acende a fatia
e leva nome e valor para o meio. **Cor de série é papel de token** (`chart-1` a
`chart-8`), nunca hexadecimal: aqui o que a peça recebe já é o valor final, e
hexadecimal fica surdo ao tema do cliente. A `PALETTE` é a lista dos oito
papéis, na ordem de uso.

**SVG no `ImageViewer` entra pelo `renderImage`**, e não pelo `src` cru: o
`Image` do core não decodifica SVG no iOS. A função recebe `uri`, `part`,
`width`, `height`, `onLoad` e `onError`; desenhe o SVG com o `SvgUri` do
`react-native-svg`, passando `onLoad` e `onError` para o giro sair, e devolva
`undefined` para a foto comum continuar no `Image`. O exemplo está na seção
"No React Native" da página do `ImageViewer`.

**O `Image` do core ignora os `headers` da fonte no Android.** No React Native
0.88, `<Image source={{ uri, headers }} />` não manda os `headers`, e a API que
pede `x-api-key` responde 401 em toda foto. No `ImageViewer`, passe
`src: { uri, headers }` (e o `thumbnail` no mesmo formato): com `headers`, a
peça baixa por `fetch`, desenha um `data:` URI, gira enquanto baixa e avisa o
erro, e o `renderImage` recebe o `uri` já baixado. Num `Image` seu, fora da
peça, o contorno é o mesmo: baixe por `fetch` e passe o `data:` URI.

**Para a barra e a linha andarem, desenhe com `ChartBar` e `ChartLine`**, no
lugar de `Rect` e `Path` crus: elas entram na montagem e vão ao valor novo
pelos tokens de movimento, e com "reduzir movimento" nascem no lugar. A linha
anda quando os VALORES mudam; quando a QUANTIDADE de pontos muda (troca de
período de 7 para 30 dias), ela troca de uma vez, porque não há ponto de
partida para os pontos novos.

```tsx
<ChartContainer config={SERIES} data={meses} className="h-56">
  {({ width, height, colors }) => (
    <Svg width={width} height={height}>
      {meses.map((mes, index) => (
        <ChartBar key={mes.mes} x={index * 40} y={height - mes.total} width={24} height={mes.total} fill={colors.receita} />
      ))}
    </Svg>
  )}
</ChartContainer>
```

A `Sparkline` fica na raiz e é desenhada com `View`: ela é o slot `chart` do
`Stat`. **As peças entram na montagem, como no web**, e a moldura (`Card`,
`PageHeader`) fica parada.

## Áudio e vídeo: um caminho por peer

O `AudioPlayer` e o `AudioRecorder` moram em `@rivocode/ui-native/audio`, atrás
do `expo-audio`; o `VideoPlayer` mora em `@rivocode/ui-native/video`, atrás do
`expo-video`. São dois caminhos porque quem manda mensagem de voz não precisa
reconstruir o app com o player de vídeo.

```sh
npx expo install expo-audio  # @rivocode/ui-native/audio
npx expo install expo-video  # @rivocode/ui-native/video
```

```tsx
import { VideoPlayer } from '@rivocode/ui-native/video'

<VideoPlayer src={video.url} poster={video.capa} label={`Vídeo de ${autor}`} />
```

A API do `VideoPlayer` é a do web, com o `src` no `VideoSource` do Expo
(`require` ou `{ uri, headers }`). O quadro é o `VideoView` sem os controles do
sistema, e a tela cheia é a do sistema.

**Vídeo da conversa no meio das fotos é o `ImageViewer`**, com
`kind: "video"` no item, `poster` e `duration`. A raiz não importa o
`expo-video`: o player entra pelo `renderVideo`, e o `renderViewerVideo` de
`@rivocode/ui-native/video` é o pronto. Sem ele, o vídeo fica parado na capa.

```tsx
import { renderViewerVideo } from '@rivocode/ui-native/video'

<ImageViewer
  images={[
    { src: foto.url, alt: foto.descricao },
    { kind: 'video', src: video.url, poster: video.capa, duration: video.segundos, alt: '' },
  ]}
  index={index}
  onIndexChange={setIndex}
  thumbnails={false}
  renderVideo={renderViewerVideo}
/>
```

**Vídeo no balão sem `poster` é o `useVideoPreview`**, do mesmo caminho: sem
ele, a `MessageMedia` nativa fica no palco escuro em 4:3, sem duração, porque
não abre o arquivo. O hook abre num player mudo (com os `headers` do `src`),
tira o primeiro quadro, a proporção e a duração e solta o player; guarda os
últimos 40 por endereço e abre dois por vez. O quadro é um `VideoThumbnail`,
que só o `Image` do `expo-image` desenha: ele entra pelo `renderPoster`.

```tsx
import { Image } from 'expo-image'
import { useVideoPreview } from '@rivocode/ui-native/video'

const previa = useVideoPreview(video.src)

<MessageMedia
  kind="video"
  src={video.src}
  aspectRatio={previa.aspectRatio}
  duration={previa.duration}
  renderPoster={previa.thumbnail ? () => <Image source={previa.thumbnail} contentFit="cover" style={{ width: '100%', height: '100%' }} /> : undefined}
/>
```

Numa conversa, o hook mora num componente do balão, e não no `renderItem` da
lista: o `renderItem` é função, e não chama hook. O componente chama o
`useVideoPreview` e devolve a `Message` com a `MessageMedia` como filha direta
- sem nó no meio, senão a hora deixa de ir por cima da mídia:

```tsx
import { Image } from 'expo-image'
import { Message, MessageMedia } from '@rivocode/ui-native/ai'
import { useVideoPreview } from '@rivocode/ui-native/video'

function BalaoDeVideo({ mensagem }: { mensagem: MensagemDeVideo }) {
  const previa = useVideoPreview(mensagem.video)
  return (
    <Message variant="chat" role={mensagem.role} time={mensagem.hora} status={mensagem.status}>
      <MessageMedia
        kind="video"
        src={mensagem.video}
        aspectRatio={previa.aspectRatio}
        duration={previa.duration}
        renderPoster={previa.thumbnail ? () => <Image source={previa.thumbnail} contentFit="cover" style={{ width: '100%', height: '100%' }} /> : undefined}
        onOpen={() => abrir(mensagem.id)}
      />
    </Message>
  )
}

<Conversation
  items={mensagens}
  keyExtractor={(mensagem) => mensagem.id}
  renderItem={({ item }) => (item.video ? <BalaoDeVideo mensagem={item} /> : <BalaoDeTexto mensagem={item} />)}
/>
```

**Baixar a mídia salva na galeria pelo `saveToGallery`**, de
`@rivocode/ui-native/media-library`, atrás do `expo-media-library` e do
`expo-file-system` (`npx expo install expo-media-library expo-file-system`). No
celular o `download` do `ImageViewer` é só a função; ela pede a permissão de
escrita, baixa com os `headers` do `src`, salva e apaga o cache. Cada falha é
um `GalleryError` com `reason` (`unavailable`, `permission`, `download`, `save`): a promessa
rejeitada vira a linha de falha da peça, embaixo do palco e anunciada, e o
padrão de `labels.downloadError` já diz o motivo de cada `reason`; a resolvida
mostra e anuncia `labels.downloaded` ("Arquivo salvo."). `downloadError` aceita
também `(erro) => string`. No Android, o Expo Go não dá acesso à galeria: ali o
`saveToGallery` sai com `unavailable`, e só roda num build de desenvolvimento.
No iOS o Expo Go tem o módulo.

```tsx
import { saveToGallery } from '@rivocode/ui-native/media-library'

<ImageViewer
  images={midia}
  index={index}
  onIndexChange={setIndex}
  download={(item) => saveToGallery(item.src, { name: item.alt, kind: item.kind })}
  labels={{ downloaded: 'Salvo na galeria.' }}
/>
```

O `useToast` aparece por cima do visualizador aberto, e de todo `Modal` da casa
(`Dialog`, `AlertDialog`, `Sheet`, `Tour`): quem prefere o toast para o sucesso
passa `labels={{ downloaded: '' }}` e chama o `toast.add` dentro da função.

No balão do `Message`, o `AudioPlayer` vai com `variant="bubble"`, como no web:
o tocar e a onda numa linha, e embaixo a duração e a hora com os tiques, que o
`Message` entrega pelo `meta` quando o player é o filho direto dele.

```tsx
<Message variant="chat" role="user" time="14:32" status="read">
  <AudioPlayer variant="bubble" src={voz.url} peaks={voz.peaks} duration={voz.segundos} />
</Message>
```

Numa conversa com vários áudios, um `useAudioSequence` por conversa, passado a
cada player: toca um por vez, e quando um termina o seguinte abaixo dele na
tela toca sozinho. O áudio que a pessoa ainda não ouviu leva `unheard`, um
ponto de acento falado "Não ouvido" que some no primeiro toque; grave a escuta
no `onHeard`. É a mesma API do web.

```tsx
import { AudioPlayer, useAudioSequence } from '@rivocode/ui-native/audio'

const sequence = useAudioSequence()

<AudioPlayer
  variant="bubble"
  src={voz.url}
  sequence={sequence}
  unheard={!voz.ouvido}
  onHeard={() => marcarOuvido(voz.id)}
/>
```

## Copiar e anexar: dois caminhos, e não um

`Clipboard` e `FileUpload` pedem peer opcional, e cada um mora num subcaminho
próprio, porque quem copia uma chave de acesso não anexa arquivo nenhum.

```sh
npx expo install expo-clipboard        # @rivocode/ui-native/clipboard
npx expo install expo-document-picker  # @rivocode/ui-native/file-upload
```

```tsx
import { Clipboard } from '@rivocode/ui-native/clipboard'
import { FileUpload, FileUploadItem, FileUploadList } from '@rivocode/ui-native/file-upload'
```

**A confirmação de copiar é dupla**: o botão troca de nome e a peça dispara
também um aviso, porque o nome trocado sob o foco não é reanunciado pelo
VoiceOver nem pelo TalkBack (`toast={false}` desliga). **A área de soltar não
existe**: o que abre o seletor é um botão de altura de controle. O `accept` fala
MIME, e o que volta é um `PickedFile` com `uri` local: `size` pode faltar, e
`maxSize` só recusa o que mediu.

## O campo sai do dado, como no web

A tabela de [components.md](components.md) vale aqui com os mesmos nomes:
`MaskedInput` com `mask="cpf"`, `"cnpj"`, `"cpfCnpj"`, `"telefone"`, `"placa"`, `"cartao"`
e `"boleto"`, `PostalCodeField`, `OTPField`, `CurrencyInput`, `DatePicker`,
`TimeField` e `NumberField` existem no `@rivocode/ui-native`, e os validadores
(`isValidCpf`, `isValidCnpj`, `isValidCpfOrCnpj`, `isValidPlate`, `isValidPixKey`, `normalizePixKey`) são o mesmo
arquivo dos dois lados. No `bun test` e no servidor, eles saem de
`@rivocode/ui-native/pure`, que não carrega o `react-native`. O `MaskedInput` abre o numérico quando o molde só tem
dígito e põe sozinho o `autoComplete` e o `textContentType` de telefone, CEP e
cartão. O molde pronto põe também o formato no `placeholder`
(`000.000.000-00` no `cpf`), como no web; o molde escrito à mão pede o seu.

**Todo campo tem a moldura do `Input`.** A altura vazia (`h-12`) e a coluna
do texto (`px-3.5` dentro da borda) são as mesmas do `Input` ao `TagsInput`,
ao `NumberField` e aos gatilhos de folha (`Select`, `Combobox`, `DatePicker`,
`TimePicker` e os irmãos), e o texto fica centrado no iOS e no Android. Com
adorno na frente (a lupa do `SearchInput`, o `R$` do `CurrencyInput`, o
prefixo do `InputGroup`), é o adorno que abre na coluna. O valor do gatilho
corta em uma linha com reticências. Não troque altura nem `px` do campo pelo
`className` para "alinhar" uma tela: os campos já se alinham entre si, e o
campo feito à mão é o que sai da coluna.

## A área segura já vem medida

O `react-native-safe-area-context` é peer **obrigatório** da raiz desde a 6.0.
`Sheet`, `Dialog`, `AlertDialog`, `ImageViewer`, `Tour` e o toast medem a área
segura sozinhos, iguais no iOS e no Android: não passe `pt-12`, `pb-8` nem
número por plataforma para eles. O `SafeAreaProvider` precisa estar acima do
`RivoProvider` - o `expo-router` já monta um; fora dele, monte você. Sem ele a
área segura mede zero e o que cobre a tela encosta no relógio.

Essas peças medem a área do **aparelho**, que o `RivoProvider` da raiz guarda,
e não a da tela: dentro de uma tela com cabeçalho do `Stack`, a navegação zera
a faixa que o cabeçalho cobre, e o `useSafeAreaInsets()` ali devolve `top: 0`
(e no Android, muitas vezes, `bottom: 0`). Por isso o `RivoProvider` mora no
`app/_layout.tsx`, por fora do `Stack`. Para o que a SUA tela desenha - a
`ActionBar`, o `footer` da `ScrollArea` - o `useSafeAreaInsets()` da tela
continua sendo a medida certa: ele já desconta o que o cabeçalho e a barra de
abas cobrem.

## O teclado já vem tratado

O `react-native-keyboard-controller` é peer obrigatório, e o `KeyboardProvider`
dele mora dentro do `RivoProvider`: não monte outro. Tela com campo é
`ScrollArea`, que rola até o campo em foco; a ação de enviar vai no `footer`,
que sobe com o teclado.

A `ScrollArea` ocupa a altura do pai (`flex-1`), então o pai precisa ter
altura. O `SafeAreaView` do `react-native-safe-area-context` **ignora
`className`**: use `<SafeAreaView style={{ flex: 1 }}>`, senão a rolagem some e
o `footer` sobe para o topo.

`Sheet` e `Dialog` (e o que abre em folha: `Select`, `Combobox`, `Menu`,
`DatePicker`, `TimePicker`, `TreeSelect`) sobem com o teclado sozinhos.

A `Sheet` fecha também no arrasto para baixo, pelo puxador e pelo cabeçalho, e
nunca pelo corpo, que fica livre para a lista rolar. Use a `Sheet` da casa, e
não o `formSheet` do roteador: é a folha da casa que conhece o teclado, o
reduzir movimento e o `Select`, o `Combobox`, o `Menu` e os seletores de data
abertos por dentro. `swipeToClose={false}` desliga o gesto; o fundo e
o voltar do Android continuam fechando.

Tela que não rola, com o campo grudado embaixo, como a conversa do
`@rivocode/ui-native/ai`, sobe pela coluna inteira: o `useKeyboardPadding()`
da raiz do pacote devolve o estilo animado que soma a altura do teclado ao pé,
e respeita o movimento reduzido. `Conversation` e `PromptInput` não sobem
sozinhos, porque dividem a coluna e porque dentro de `Sheet` subiriam duas
vezes.

A coluna do chat mora dentro de um `SafeAreaView` com `edges={['bottom']}`:
sem ele, com o teclado fechado, o campo encosta na barrinha do iPhone. Só que
a altura do teclado já cobre essa faixa, então, com o teclado aberto, a área
segura seria contada duas vezes e sobraria uma faixa vazia de uns 34pt entre o
campo e o teclado. Passe a mesma área segura ao hook, em `bottomInset`, para
ele descontar.

```tsx
import Animated from 'react-native-reanimated'
import { SafeAreaView, useSafeAreaInsets } from 'react-native-safe-area-context'
import { useKeyboardPadding } from '@rivocode/ui-native'
import { Conversation, PromptInput } from '@rivocode/ui-native/ai'

const insets = useSafeAreaInsets()
const keyboard = useKeyboardPadding({ bottomInset: insets.bottom })

<SafeAreaView edges={['bottom']} style={{ flex: 1 }}>
  <Animated.View style={keyboard} className="flex-1">
    <Conversation items={mensagens} renderItem={desenhar} keyExtractor={(m) => m.id} />
    <PromptInput
      value={texto}
      onValueChange={setTexto}
      onSubmit={enviar}
      streaming={respondendo}
      onStop={parar}
    />
  </Animated.View>
</SafeAreaView>
```

Enquanto a resposta chega, inclusive antes do primeiro pedaço, o `PromptInput`
recebe `streaming`, e não `disabled`: o `disabled` tira o campo, e no iOS o
campo que deixa de ser editável perde o foco e fecha o teclado a cada envio.

A citação de uma resposta leva até a original sozinha quando o `replyTo.id` é
a chave que o `keyExtractor` dá à original: a lista rola com o
`scrollToIndex` e a linha fica em `selected` por um instante. Não existe
`messageId` no nativo, e nem `contextMenu`: responder é arrastar o balão, com
a ação de acessibilidade "Responder". Para pular depois de carregar o
histórico, o `actionsRef` da `Conversation` dá o `scrollToMessage(id)`.

Para anunciar ao leitor de tela o que mudou sem foco, como o "Pedido enviado"
depois de um toque, o pacote exporta `announce(frase)` e o `useAnnounce(frase)`,
que fala quando a frase muda. São os mesmos que as peças usam, com o desvio do
Android, que já lê a região viva, quando `liveRegion` vem ligado.

## O que nunca fazer no nativo

- `KeyboardAvoidingView` ou `useAnimatedKeyboard` em volta das peças: o teclado
  já é descontado por elas, e o segundo desconto empurra a tela duas vezes. A
  exceção é a coluna sem `ScrollArea`, e ali é o `useKeyboardPadding()`.
- Classe com var arbitrária (`h-[--rc-control-md]`) ou `translate-*`: o
  compilador do `react-native-css` não tolera var viva nem a shorthand
  `translate`.
- `tabular-nums` fora do `Text` da casa: o NativeWind descarta o
  `font-variant-numeric`, e só o `Text` do pacote lê o token e põe o
  `fontVariant` no estilo. No `Text` do `react-native`, ou numa `View`, o
  número continua mudando de largura.
- Remover o `browserslist` moderno do `package.json` do app: sem ele, o passe
  web do Expo reescreve o `light-dark()` num polyfill que mata a compilação.
- Prometer tema de cliente em runtime, ou escrever `theme={{ light, dark }}`.
- `tone="neutral"` em todo `Text` só para não sair preto: o `Text` do topo já
  sai em `text-fg`. Passe `tone` quando a cor for outra.
- Escrever `density`: a prop não existe no pacote, porque alvo de toque não
  encolhe.
- `Indicator` no sino do `NotificationCenter`: ele já desenha o número das não
  lidas, e o segundo duplica.
- `TextInput` da raiz no lugar do `Input`: o `TextInput` exportado é o da
  plataforma só com a fonte da casa, sem borda, sem `Field`, sem `invalid`.
  Ele serve de base para campo montado à mão; campo de formulário é `Input`.
- Esperar o molde `dd/mm/aaaa` no `DatePicker` nativo: aqui ele é um botão que
  abre a folha do mês, e o texto de espera é "Selecione a data"; a data
  escolhida sai em `dd/mm/aaaa`. Data digitada é o `MaskedInput` com
  `mask="data"`.
- `DateRangePicker` sem `Field` em volta: o `label` dele só nomeia o gatilho e
  o título da folha, e não aparece escrito. O rótulo visível é o do `Field`.

- Ícone desenhado à mão (caractere, `View` girada, SVG próprio): o ícone é do
  `lucide-react-native`, com o mesmo nome do web.
- `border-dashed` numa `View` que tem filho com borda: o estilo da borda anda por
  variável, que herda, e o `Button` de dentro sai tracejado também. O tracejado
  vai numa `View` irmã `absolute inset-0`.
- `entering` com `.withInitialValues(...)` em tela que roda no navegador: no
  react-native-web o Reanimated termina a animação deixando a `View` em
  `position: absolute`, fora do fluxo, e o vizinho de baixo sobe por cima dela.
- Esquecer `accessibilityRole` e `accessibilityState` em controle montado à mão.
- `allowFontScaling={false}`, ou `maxFontSizeMultiplier` abaixo de 1,5, para "o
  layout não quebrar". Quem aumentou a fonte do aparelho precisa dela. O layout
  quebra linha (`flex-wrap`, nada de altura fixa em linha com texto) e o corte é
  `lineClamp` com o texto inteiro no detalhe. Confira cada tela com a maior
  fonte do sistema ligada.
- Alinhar texto de `TextInput` por classe ou pela prop `textAlign`: os dois
  alvos só leem `style={{ textAlign: "center" }}`. O mesmo vale para atalho
  lógico de borda (`border-x`): escreva `border-l border-r`.
- A utility de divisória entre filhos do Tailwind: o seletor de filho não
  existe no RN.
- Nome de classe em comentário: o scanner do Tailwind lê a fonte crua e gera a
  classe.
