# MessageMedia

A foto, o vídeo, o documento ou a localização dentro do balão de uma
conversa: a mídia na proporção dela, o vídeo como miniatura com o play no
centro e a duração no canto, o arquivo e o lugar como cartão, e o toque que
abre a mídia inteira. Vive em `@rivocode/ui/ai`, ao lado da `Message`, que
reconhece a peça como filho direto e põe a hora no lugar certo. Filho
direto quer dizer sem componente seu no meio: embrulhada num componente do
app, ela não é reconhecida e perde a hora por cima e a borda apertada. E
tem de ser a filha **única**: um `{cond ? <X /> : null}` ao lado já faz dos
filhos uma lista, e a hora some da foto. O que é condicional vai para fora
da `Message` ou para o `caption`.

```tsx
import { Message, MessageMedia } from '@rivocode/ui/ai'

<Message variant="chat" role="assistant" author="Marina Costa" time="14:32">
  <MessageMedia kind="video" src={video.url} poster={video.capa} duration={12} onOpen={abrirVideo} />
</Message>
<Message variant="chat" role="user" time="14:33" status="read">
  <MessageMedia kind="image" src={foto.url} width={1600} height={1000} caption="Fachada nova da loja" onOpen={abrirFoto} />
</Message>
```

## Documento

`kind="document"` é o cartão do arquivo: o ícone do tipo num quadro, o `name`
como título (cortado com reticências quando não cabe), e embaixo o tipo por
extenso e o tamanho ("PDF · 120 KB"). O tipo sai da extensão do `name`, e o
`mimeType` decide quando ela falta: "PDF", "Planilha", "Documento do Word",
"Documento" (o texto que não é do Word), "Imagem",
"Arquivo compactado", "Apresentação", e a extensão em maiúscula ("DWG") para o
que a peça não conhece. `size` é em bytes, escrito pelo mesmo formatador do
`FileUpload`.

À direita fica o Baixar, com o mesmo `download` da foto e do vídeo: `true` baixa
o `src` e salva com o `name`; uma função fica com o download e gira até a
promessa acabar. Dentro de uma `Message`, o botão é o do cartão e não se repete
nas ações; o item "Baixar" do `contextMenu` e a linha de falha continuam os da
`Message`. Fora dela, o cartão desenha o botão e a linha sozinho. Com `onOpen`,
o resto do cartão é o botão que abre o arquivo.

**A legenda igual ao `name` não aparece.** O WhatsApp manda o nome do arquivo
como legenda quando quem enviou não escreveu nenhuma, e o balão diria
"10.pdf" duas vezes. A legenda diferente do nome sai embaixo do cartão, como na
foto.

```tsx
<Message variant="chat" role="assistant" author="Marina Costa" time="10:02" contextMenu>
  <MessageMedia
    kind="document"
    src={{ uri: anexo.url, headers }}
    name={anexo.nome}
    mimeType={anexo.tipo}
    size={anexo.bytes}
    caption={anexo.legenda}
    onOpen={abrirAnexo}
    download
  />
</Message>
```

## Localização

`kind="location"` é o cartão do lugar: o alfinete, o `name` ("Localização" sem
ele), o `address` embaixo ("Abrir no mapa" sem ele) e o ícone de sair no fim.
O cartão inteiro é o botão do `onOpen`, que abre o mapa que a tela escolher.

**A peça não desenha mapa.** A miniatura de um serviço de mapas mandaria as
coordenadas do contato para fora, e isso é decisão do app. Quem quiser o mapa
passa `renderMap`, que entra em cima da linha do lugar, dentro do mesmo botão.

```tsx
<MessageMedia
  kind="location"
  name={lugar.nome}
  address={lugar.endereco}
  onOpen={() => window.open(linkDoMapa(lugar), '_blank', 'noopener')}
/>
```

## A hora aparece uma vez só

Dentro de uma `Message variant="chat"`, a hora e os tiques vão por cima da
mídia, no canto de baixo, numa pílula escura (o `media-stage` a 70%), quando
não há legenda: assim leem sobre foto branca e sobre foto escura, a 4,5:1 no
pior caso. Com `caption`, a legenda sai embaixo da mídia e a hora vai depois
dela, na cor de sempre. Nunca nos dois lugares. O balão aperta a borda em volta
da mídia, e a legenda e a hora ganham o respiro de volta.

No `document` e no `location` não há foto para pôr a hora por cima: ela vai
embaixo do cartão, na cor de sempre, ou depois da legenda quando ela existe.

Por cima da mídia, os tiques ficam na cor da pílula, e `read` e `delivered`
se distinguem pela palavra que o leitor de tela ouve, e não pela cor: o tom de
acento do tema claro não lê sobre o fundo escuro.

## Vídeo sem player

`kind="video"` é a miniatura, e não o player: o `poster` na proporção do
vídeo, o play no centro e a duração ("0:12") no canto de baixo, sem barra de
controles. O toque chama `onOpen`, e quem decide o que abre é a tela: o
`VideoPlayer` numa folha ou em tela cheia. Sem `poster`, o web mostra o
primeiro quadro do arquivo, mudo e fora do foco; no celular, o palco escuro com
o play.

## A proporção

`aspectRatio` vence, depois `width` e `height`. Passe um dos dois quando a API
souber, e o balão nasce do tamanho certo, sem pular quando a imagem chega. Sem
nenhum, o balão nasce em 4:3 e passa para a proporção da mídia quando ela
carrega. A proporção fica entre 9:16 e 2:1; a mídia mais alta ou mais larga
que isso é recortada pelo centro, para um vídeo vertical não ocupar a tela
inteira.

## O endereço

`src` e `poster` aceitam o endereço ou `{ uri, headers }`, o mesmo formato do
`ImageViewer`, para a foto que vem de uma API com `x-api-key`. Com `headers`, a
peça baixa por `fetch` e mostra o resultado; o vídeo em si não é baixado aqui.
Foto que falha mostra o aviso no lugar, e o balão continua do mesmo tamanho.

## Baixar

`download` liga o Baixar da `Message` que tem a mídia como filha direta: o
botão nas ações e o item "Baixar" do `contextMenu` (no `document`, o botão é o
do cartão). É o mesmo download do
`ImageViewer`: `true` baixa o `src` com os mesmos `headers` e salva com o nome
do endereço ou do `label`; uma função fica com o download, e a promessa
rejeitada vira a linha de falha da `Message`. Fora de uma `Message`, a prop não
desenha nada na foto e no vídeo; no documento, o cartão desenha o botão.

```tsx
<Message variant="chat" role="assistant" author="Marina Costa" time="14:32" contextMenu>
  <MessageMedia kind="image" src={{ uri: foto.url, headers }} label="Fachada da loja" onOpen={abrir} download />
</Message>
```

## Nomes

A foto se chama "Foto", o vídeo "Vídeo de 12 segundos", com a duração por
extenso, o documento "Documento 10.pdf, PDF, 120 KB", e a localização pelo
nome e pelo endereço ("Loja Centro, Rua XV de Novembro, 100"). `label` troca o
nome inteiro ("Comprovante do Pix"), e `labels` troca as palavras (`image`,
`video`, `videoOf`, `file`, `location`, `openMap`, e `download`,
`downloading`, `downloadError` e `downloaded` do Baixar do cartão fora de uma
`Message`). Sem `onOpen`, a mídia é imagem, e não botão.

```tsx
<MessageMedia kind="image" src={comprovante.url} label="Comprovante do Pix" onOpen={abrir} />
```

## Partes

`classNames` alcança `media` (a caixa da foto, da miniatura ou do cartão),
`play` e `duration` do vídeo, `card` (a linha do cartão), `icon` (o quadro do
ícone), `title`, `detail` (a linha de apoio), `action` (o Baixar) e `map` do
documento e da localização, e `caption` e `meta` (a caixa da hora, por cima ou
embaixo) em todos.

## Quando não usar

- **A galeria de fotos de um registro**, fora da conversa, é `ImageViewer`, que
  já traz a grade de miniaturas e o visualizador. A `MessageMedia` é uma mídia
  por balão, e o `ImageViewer` é o que ela abre.
- **O vídeo que toca no lugar**, com barra e velocidade, é `VideoPlayer`. A
  miniatura do balão não toca: a conversa rola, e um vídeo tocando no meio
  dela é o que ninguém pediu.
- **O anexo fora da conversa** (o PDF de um pedido, a lista de arquivos de um
  registro) é `FileUploadItem` ou um `Item` com o ícone do tipo. O cartão do
  `document` é o arquivo que chegou numa mensagem, com a hora dela.
- **O endereço num formulário ou num detalhe de registro** é texto num
  `DescriptionList`, e não o cartão do `location`, que é o lugar que alguém
  mandou na conversa.

## No React Native

Traduz, no caminho próprio `@rivocode/ui-native/ai`, com os mesmos `kind`, `src`, `poster`, `width`, `height`, `aspectRatio`, `duration`, `onOpen`, `label`, `caption` e os mesmos nomes ("Foto", "Vídeo de 12 segundos"). Dentro de uma `Message` de chat, a hora vai por cima da mídia sem legenda, na mesma pílula escura do web, e depois da legenda com ela.

**Documento e localização, como no web.** `kind="document"` é o mesmo cartão, com o mesmo ícone do lucide por tipo, o `name` numa linha só, o tipo e o tamanho embaixo, e `mimeType` e `size` com o mesmo sentido; a legenda igual ao `name` também não aparece. `kind="location"` é o mesmo cartão do lugar, com `name`, `address`, `onOpen` e `renderMap`, e sem mapa desenhado pela peça. A hora vai embaixo do cartão. Os nomes falados são os mesmos ("Documento 10.pdf, PDF, 120 KB").

**O Baixar do documento é uma função.** No web o `download={true}` baixa o `src` pelo navegador; aqui não há onde salvar sem o `expo-file-system`, então o `download` do cartão só aceita a função, e quem salva é o app (o `saveToGallery` serve para foto e vídeo; documento vai pelo `expo-file-system` ou pelo `expo-sharing`). O botão é o `IconButton` do cartão, gira enquanto a promessa corre, e o fim ou a falha saem numa linha embaixo do cartão, anunciada. Não há menu do toque longo, como na `Message`.

**Sem peer.** A miniatura do vídeo é o `Image` do core com o `poster`, e não um player: o `expo-video` mora em `@rivocode/ui-native/video`, e o caminho de IA não o cobra de quem só mostra foto. Sem `poster`, o vídeo é o palco escuro com o play, em 4:3 e sem duração; o web mostra o primeiro quadro, que aqui pede o módulo nativo.

**O primeiro quadro vem do `useVideoPreview`, de `@rivocode/ui-native/video`.** Ele abre o arquivo num player mudo do `expo-video`, com os `headers` do `src`, tira o quadro, a proporção e a duração, e solta o player. Proporção e duração entram pelas props de sempre. O quadro é um `VideoThumbnail`, imagem nativa que o `Image` do core não abre e o do `expo-image` abre: ele entra pelo `renderPoster`, que só existe no celular e vence o `poster`. Sem o `expo-image` no app, fique com a proporção e a duração, e o palco continua escuro.

```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
  }
/>
```

O hook guarda o resultado por endereço, os últimos 40, então rolar a conversa de volta não abre o arquivo de novo; abre no máximo dois por vez, e o resto espera na fila; e o balão que sai da tela antes de terminar solta o player dele. O arquivo que não abre dá `status: "error"` e não fica guardado: montar de novo tenta de novo.

**`{ uri, headers }` baixa por `fetch`**, como no `ImageViewer` nativo, e mostra um `data:` URI, porque o `Image` do Android ignora os `headers` da fonte. A proporção sai do `onLoad` da imagem quando nenhuma medida vem.

**Sem `download` na foto e no vídeo.** O Baixar do web vive no botão e no menu do botão direito da `Message`, e o celular não tem esse menu. Para salvar a mídia, ponha um `IconButton` nas `actions` da `Message` que chame o `saveToGallery` de `@rivocode/ui-native/media-library`.

As partes vestem pelo mesmo `classNames` do web: `media`, `play`, `duration`, `caption`, `meta`, `card`, `icon`, `title`, `detail`, `action` e `map`.

**No iOS e no Android.** O pedido de permissão do `saveToGallery` é o do sistema. No iOS pede só para adicionar fotos; no Android 13 ou mais novo pede foto e/ou vídeo conforme o `kind`; no Android 9 ou mais velho pede acesso ao armazenamento. Recusado, o erro é o mesmo nos dois: `GalleryError` com `reason: 'permission'`.

## Importação

```tsx
import { MessageMedia } from '@rivocode/ui/ai'
```

## Exemplos

### Foto e vídeo no balão

```tsx
import { Message, MessageMedia } from '@rivocode/ui/ai'

function picture(hue: number, title: string, width: number, height: number) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0" stop-color="hsl(${hue} 45% 60%)"/>
      <stop offset="1" stop-color="hsl(${hue + 50} 50% 24%)"/>
    </linearGradient></defs>
    <rect width="${width}" height="${height}" fill="url(#g)"/>
    <text x="40" y="80" font-family="sans-serif" font-size="44" fill="white">${title}</text>
  </svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

export function InBubble() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Message variant="chat" role="assistant" author="Marina Costa" time="14:32">
        <MessageMedia
          kind="video"
          src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
          poster={picture(110, 'Obra', 720, 1120)}
          width={720}
          height={1120}
          duration={12}
          onOpen={() => {}}
        />
      </Message>
      <Message variant="chat" role="user" time="14:33" status="read">
        <MessageMedia
          kind="image"
          src={picture(200, 'Fachada', 1600, 1000)}
          width={1600}
          height={1000}
          caption="Fachada nova da loja"
          onOpen={() => {}}
        />
      </Message>
    </div>
  )
}
```

### Foto sem legenda

```tsx
import { Message, MessageMedia } from '@rivocode/ui/ai'

function picture(hue: number, title: string, width: number, height: number) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0" stop-color="hsl(${hue} 45% 60%)"/>
      <stop offset="1" stop-color="hsl(${hue + 50} 50% 24%)"/>
    </linearGradient></defs>
    <rect width="${width}" height="${height}" fill="url(#g)"/>
    <text x="40" y="80" font-family="sans-serif" font-size="44" fill="white">${title}</text>
  </svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

export function PhotoOnly() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Message variant="chat" role="user" time="09:14" status="delivered">
        <MessageMedia kind="image" src={picture(40, 'Recibo', 1200, 1200)} aspectRatio={1} label="Recibo da compra" onOpen={() => {}} />
      </Message>
    </div>
  )
}
```

### Com o Baixar nas ações e no menu do botão direito

```tsx
import { Message, MessageMedia } from '@rivocode/ui/ai'

function picture(hue: number, title: string, width: number, height: number) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0" stop-color="hsl(${hue} 45% 60%)"/>
      <stop offset="1" stop-color="hsl(${hue + 50} 50% 24%)"/>
    </linearGradient></defs>
    <rect width="${width}" height="${height}" fill="url(#g)"/>
    <text x="40" y="80" font-family="sans-serif" font-size="44" fill="white">${title}</text>
  </svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

export function WithDownload() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Message variant="chat" role="assistant" author="Marina Costa" time="14:32" contextMenu>
        <MessageMedia
          kind="image"
          src={picture(160, 'Planta', 1600, 1200)}
          width={1600}
          height={1200}
          label="Planta do segundo andar"
          onOpen={() => {}}
          download
        />
      </Message>
    </div>
  )
}
```

### Documento no balão

```tsx
import { Message, MessageMedia } from '@rivocode/ui/ai'

export function Document() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Message variant="chat" role="assistant" author="Marina Costa" time="10:02" contextMenu>
        <MessageMedia
          kind="document"
          src="https://exemplo.com.br/api/midia/10"
          name="Boleto de novembro.pdf"
          size={122_880}
          caption="Boleto de novembro.pdf"
          onOpen={() => {}}
          download
        />
      </Message>
      <Message variant="chat" role="user" time="10:05" status="read">
        <MessageMedia
          kind="document"
          name="Fechamento de outubro.xlsx"
          size={48_300}
          caption="Segue a planilha com o fechamento"
          download={() => new Promise((resolve) => setTimeout(resolve, 1200))}
        />
      </Message>
    </div>
  )
}
```

### Localização no balão

```tsx
import { Message, MessageMedia } from '@rivocode/ui/ai'

export function Location() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Message variant="chat" role="assistant" author="Marina Costa" time="11:20">
        <MessageMedia kind="location" name="Loja Centro" address="Rua XV de Novembro, 100 - Curitiba" onOpen={() => {}} />
      </Message>
      <Message variant="chat" role="user" time="11:21" status="delivered">
        <MessageMedia kind="location" onOpen={() => {}} />
      </Message>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `kind` | `MessageMediaKind` | sim |  | - | `image` e a foto, inteira no balao; `video` e a miniatura com o play no centro e a duracao no canto; `document` e o cartao do arquivo, com o icone do tipo, o nome, o tipo e o tamanho, e o Baixar a direita; `location` e o cartao do lugar, que abre no mapa. |
| `address` | `string` |  |  | - | Em `location`, o endereco: a linha de baixo do cartao, e sem ele "Abrir no mapa". |
| `aspectRatio` | `number` |  |  | - | A proporcao, largura sobre altura. |
| `caption` | `ReactNode` |  |  | - | A legenda, embaixo da midia. |
| `classNames` | `Partial<Record<"action" \| "caption" \| "card" \| "detail" \| "duration" \| "icon" \| "map" \| "media" \| "meta" \| "play" \| "title", string>>` |  |  | - | Classe por parte: `media`, `play` e `duration` da foto e do video; `card` (a linha do cartao), `icon` (o quadro do icone), `title`, `detail` (a linha de apoio), `action` (o Baixar) e `map` no `document` e no `location`; e `caption` e `meta` em todos. |
| `download` | `boolean \| (() => void \| Promise<unknown>)` |  |  | - | Liga o Baixar da `Message` que tem esta midia como filha direta: o botao nas acoes e o item do `contextMenu`. |
| `duration` | `number` |  |  | - | A duracao do video, em segundos: o "0:12" do canto e o "Video de 12 segundos" do leitor de tela. |
| `height` | `number` |  |  | - | A altura da midia, em pixels, junto com `width`. |
| `label` | `string` |  |  | - | O nome acessivel. |
| `labels` | `Partial<MessageMediaLabels>` |  |  | - | Os textos da peca: `image` ("Foto"), `video` ("Video"), `videoOf`, o video com a duracao falada, `file` (a palavra que abre o nome do cartao do arquivo), `location` ("Localização"), `openMap` ("Abrir no mapa"), e os do Baixar do `document` fora de uma `Message`: `download`, `downloading`, `downloadError` e `downloaded`. |
| `meta` | `ReactNode` |  |  | - | A hora e os tiques. |
| `mimeType` | `string` |  |  | - | Em `document`, o tipo do arquivo ("application/pdf"), quando o `name` nao tem extensao. |
| `name` | `string` |  |  | - | Em `document`, o nome do arquivo ("10.pdf"): o titulo do cartao, cortado com reticencias, e de onde sai o tipo pela extensao. |
| `onOpen` | `(() => void)` |  |  | - | Chamado no clique ou no Enter: abra o `ImageViewer` com a foto, o `VideoPlayer` em tela cheia com o video, o documento numa aba ou o lugar no mapa. |
| `poster` | `ImageSource` |  |  | - | A miniatura do video, no mesmo formato do `src`. |
| `renderMap` | `(() => ReactNode)` |  |  | - | Em `location`, o mapa desenhado pelo app, em cima da linha do lugar. |
| `size` | `number` |  |  | - | Em `document`, o tamanho em bytes, escrito pela peca ("120 KB") ao lado do tipo. |
| `src` | `ImageSource` |  |  | - | A foto, ou o arquivo do video: o endereco, ou `{ uri, headers }` para a imagem que pede cabecalho (uma API com `x-api-key`), como no `ImageViewer`. |
| `width` | `number` |  |  | - | A largura da midia, em pixels, junto com `height`: so a proporcao conta, e ela vale desde o primeiro quadro, sem o balao pular quando a imagem chega. |

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

## Ver também

- [AILabel](/componentes/ai-label.md)
- [Conversation](/componentes/conversation.md)
- [Message](/componentes/message.md)
- [PromptInput](/componentes/prompt-input.md)
- [ShimmerText](/componentes/shimmer-text.md)
- [ToolCall](/componentes/tool-call.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
