# ImageViewer

Uma grade de miniaturas que abre a foto em tela cheia: fotos de um imóvel,
comprovantes anexados a uma despesa, a vistoria de um veículo. Na tela cheia a
pessoa navega entre as imagens, aproxima para ler o detalhe e fecha voltando
exatamente para onde estava.

```tsx
<ImageViewer
  images={[
    { src: '/fotos/fachada.jpg', alt: 'Fachada do prédio comercial' },
    { src: '/fotos/recepcao.jpg', alt: 'Recepção com balcão de madeira' },
  ]}
/>
```

É montada sobre o `Dialog` da casa: o foco fica preso dentro, `Esc` fecha, o
fundo fica inerte para o leitor de tela e o tema acompanha o portal.

## O palco é sempre escuro

A tela cheia abre num palco escuro nos dois temas, como a galeria do celular e
os visualizadores de foto de mercado: fundo claro em volta da foto briga com
ela e estoura o brilho. O fundo, a legenda, o contador e os controles (fechar,
setas e zoom) leem os papéis fixos `media-*` (`bg-media-stage`,
`bg-media-control`, `text-media-fg`, `text-media-fg-muted`,
`border-media-border` e `media-disabled` para o controle desabilitado), e não
os papéis do tema.

Eles moram em `scales.css`, fora dos temas, pelo mesmo motivo do par do
`QRCode`: o palco continua escuro no tema claro e em todo tema de cliente, sem
o cliente declarar nada. O `check:contrast` mede os pares: o palco escuro,
legenda e contador a 4,5:1, ícone, contorno e anel de foco a 3:1, e o controle
desabilitado visível e mais fraco que o vivo. A grade de miniaturas continua na
página, e com as cores do tema.

O tema não declara `--rc-media-*`. Para mudar o palco num produto, vista as
partes pelo `classNames` (`viewer`, `counter`, `caption`), com token.

## As imagens

`images` é a lista, na ordem da navegação. Cada imagem tem `src`, `alt`
obrigatório, `caption` opcional e `thumbnail`, a versão pequena que a grade usa
(sem ela, a grade carrega o `src`).

**Imagem que pede cabeçalho.** `src` e `thumbnail` aceitam também
`{ uri, headers }`, para a foto que vem de uma API com chave (`x-api-key`) e que
o `<img>` não sabe pedir. Com `headers`, a peça baixa por `fetch`, mostra pelo
`URL.createObjectURL` e revoga o endereço ao desmontar; enquanto baixa, o palco
gira, e se a resposta não for 2xx, diz que não carregou. Cada endereço baixa uma
vez só enquanto a peça vive. Sem `headers`, nada muda: o endereço vai direto
para o `<img>`.

```tsx
const fotos = mensagens.map((m) => ({
  src: { uri: m.fotoUrl, headers: { 'x-api-key': chave } },
  alt: m.descricao,
}))
```

**O `alt` é obrigatório no tipo**, e não por capricho: ele é o nome do botão da
miniatura, e é o que o leitor de tela ouve a cada troca de imagem, junto com a
posição ("3 de 8: Recepção com balcão de madeira"). Uma galeria sem `alt` é,
para quem não enxerga, uma fileira de botões sem nome.

A `caption` aparece embaixo da imagem aberta, e vale para o que o `alt` não
diz: quando foi tirada, quem enviou, o que a pessoa deve reparar.

## Num chat: quem mandou, quando, e as ações

Na conversa, cada imagem pode levar `author` e `date`, já escritos pelo app
("Marina Costa", "hoje, 14:33"). Com eles, o alto do visualizador mostra quem
mandou e quando à esquerda, e o contador passa para perto do xis. A imagem sem
os dois continua com o contador à esquerda.

`actions` desenha a barra de baixo, que o app escolhe: Responder, Encaminhar,
Salvar. A função recebe a imagem aberta e o índice dela, e é chamada de novo a
cada troca. **O que vai nela já sai no contraste do palco**: a barra redefine
os papéis do tema (`fg`, `fg-muted`, `surface`, `border-strong`, `ring` e o
resto) para os `media-*`, então um `Button variant="ghost"` ou um `IconButton`
da casa fica claro sobre o palco escuro sem classe nenhuma.

```tsx
const fotos = mensagens.map((m) => ({
  src: m.fotoUrl,
  alt: m.descricao,
  author: m.autor,
  date: m.horaEscrita,
}))

<ImageViewer
  images={fotos}
  index={index}
  onIndexChange={setIndex}
  thumbnails={false}
  actions={(foto, posicao) => (
    <>
      <Button variant="ghost" onClick={() => responder(mensagens[posicao])}>Responder</Button>
      <Button variant="ghost" onClick={() => encaminhar(mensagens[posicao])}>Encaminhar</Button>
      <Button variant="ghost" render={<a href={foto.src} download />}>Salvar</Button>
    </>
  )}
/>
```

## Baixar

`download` liga o botão Baixar na barra de cima, ao lado do zoom e do xis.
Desligado por padrão: a foto de um imóvel não é, por si, coisa que se baixa.

- **`download` (ou `download={true}`) baixa pela própria peça** o item aberto,
  foto ou vídeo, com os mesmos `headers` do `src`, e salva com o nome do
  endereço (`fachada.jpg`). Sem extensão no endereço, o nome vem do `alt` e a
  extensão do tipo que o servidor mandou. O arquivo passa por um `Blob` e um
  `<a download>`, e o endereço temporário é revogado logo depois.
- **O servidor que recusa a leitura** (CORS) não deixa o navegador ler o
  arquivo. Sem `headers`, a peça abre o arquivo em outra aba, onde a pessoa
  salva pelo navegador; com `headers`, não abre, porque a aba iria sem o
  cabeçalho. Nos dois casos a falha aparece embaixo do palco e é anunciada.
- **Uma função fica com o download**: recebe o item e o índice, como o
  `actions`. Se devolver uma promessa, o botão gira e diz "Baixando…" até ela
  acabar; a resolvida mostra `labels.downloaded` ("Arquivo salvo.") e a
  rejeitada, `labels.downloadError`.

```tsx
<ImageViewer images={fotos} index={index} onIndexChange={setIndex} thumbnails={false} download />

<ImageViewer
  images={fotos}
  index={index}
  onIndexChange={setIndex}
  download={(foto, posicao) => baixarPeloServidor(mensagens[posicao].id)}
/>
```

O botão não trava enquanto busca: ele continua com o foco, troca o nome para
"Baixando…" e ignora o segundo clique. O fim sai na mesma linha embaixo do
palco, e é anunciado: "Arquivo salvo." quando a promessa resolve, a falha
quando rejeita. Trocar de item limpa a linha. Os textos são `labels.download`,
`labels.downloading`, `labels.downloaded` e `labels.downloadError`. O
`downloadError` aceita também uma função do erro, para dizer o motivo, e
`downloaded: ""` cala o sucesso. A função que não devolve promessa não ganha
linha de sucesso: a peça não sabe quando ela acabou.

```tsx
<ImageViewer
  images={fotos}
  index={index}
  onIndexChange={setIndex}
  download={(foto) => baixarPeloServidor(foto.src)}
  labels={{
    downloaded: "Foto salva.",
    downloadError: (erro) =>
      erro instanceof Error && erro.message === "HTTP 413"
        ? "O arquivo é grande demais para baixar."
        : "Não foi possível baixar o arquivo.",
  }}
/>
```

## Foto e vídeo no mesmo visualizador

Como na galeria do WhatsApp, a mídia da conversa passa toda pelo mesmo
visualizador, na ordem em que foi mandada: foto, vídeo, foto. O item com
`kind: "video"` toca o `src` num `VideoPlayer` no palco, com o mesmo
cabeçalho, o mesmo contador, o mesmo xis e a mesma barra de ações das fotos.
Sem `kind`, o item é foto, como sempre foi.

```tsx
const midia = mensagens.map((m) =>
  m.tipo === 'video'
    ? { kind: 'video', src: m.arquivo, poster: m.capa, duration: m.segundos, alt: '', author: m.autor, date: m.hora }
    : { src: m.arquivo, alt: m.descricao, author: m.autor, date: m.hora },
)

<ImageViewer images={midia} index={index} onIndexChange={setIndex} thumbnails={false} />
```

- **`poster`** é a capa: aparece na miniatura e no palco até o primeiro toque,
  e com ela o arquivo só baixa quando a pessoa toca no play. Sem ela, o palco
  pede só os metadados e mostra o primeiro quadro que o navegador conseguir.
- **`duration`**, em segundos, aparece no player antes de o arquivo carregar e
  dá o nome falado: com `alt` vazio, o leitor de tela ouve "2 de 3: Vídeo de 12
  segundos", a mesma frase do `MessageMedia` no balão. Um `alt` escrito vence.
- **O player só existe no item aberto.** Ao passar para a foto seguinte ele sai
  de cena, e o vídeo para junto: não fica som tocando atrás de uma foto.
- **Sem zoom no vídeo.** Os botões de mais e menos desabilitam, e o duplo
  clique, a roda com `Ctrl`, a pinça e o `+`, `-` e `0` não fazem nada.
- **As setas dentro do player buscam no vídeo**, de 5 em 5 segundos, como em
  todo `VideoPlayer`; com o foco fora dele, trocam de item. `PageUp` e
  `PageDown` trocam de item sempre. O deslizar de lado troca de item quando
  começa no quadro, e não na faixa de controles.
- O `src` com `{ uri, headers }` vale para a foto e para o `poster`. O arquivo
  do vídeo vai direto para o `<video>`, que não manda cabeçalho: sirva o vídeo
  por endereço assinado.

## Navegar

As setas na lateral, as setas do teclado, `PageUp` e `PageDown` e o deslizar de
lado passam de imagem. O contador "3 de 8" fica no alto, à esquerda. Na primeira
e na última, a seta daquele lado desabilita; com `loop`, a navegação dá a volta.

Se a seta desabilita com o foco nela, o foco desce para a área da imagem, e não
se perde na página: as teclas do visualizador continuam valendo. O mesmo vale
para o mais e o menos do zoom, no máximo e no tamanho que cabe.

A vizinha de cada lado é carregada antes de a pessoa pedir, então a troca de
imagem não espera a rede. Enquanto a imagem aberta carrega, um giro ocupa o
lugar dela; se ela não carrega, a tela diz isso em vez de girar para sempre.

## Zoom

Os botões de mais e menos aproximam de uma vez e meia em uma vez e meia, até
`maxZoom` (4 por padrão). O duplo clique na imagem dobra o zoom no ponto
clicado, e o segundo volta ao tamanho que cabe. O duplo clique nos botões de
anterior e próxima só troca de imagem duas vezes, sem aproximar. A roda do mouse aproxima com `Ctrl` apertado,
que é o mesmo evento que o gesto de pinça do trackpad manda; no toque, a pinça
de dois dedos aproxima direto.

Aproximada, a imagem se arrasta para ver o resto, e o deslizar deixa de trocar
de imagem: o dedo que arrasta a foto aproximada não pode, de repente, mudar de
foto. No teclado, `+` e `-` aproximam e afastam, e `0` volta ao tamanho que
cabe.

**Com zoom, as quatro setas percorrem a foto**, de 40 em 40 pixels, sem passar
da borda, e são o arrastar de quem não usa ponteiro. A troca de imagem fica com
`PageUp`, `PageDown` e os botões da lateral. Trocar de imagem sempre volta o
zoom ao começo.

## Fechar e voltar

`Esc`, o xis no alto ou o `onIndexChange(null)` fecham. **O foco volta para a
miniatura da imagem que estava aberta**, e não necessariamente para a que abriu:
quem abriu a segunda foto, andou até a quinta e fechou, continua a partir da
quinta na grade, com a página rolada até ela.

## Controlado

`index` e `onIndexChange`: o índice da imagem aberta, contando de zero, ou
`null` com o visualizador fechado. Com `thumbnails={false}` a grade some, e quem
abre é o `index`, a partir de qualquer botão da tela:

```tsx
const [index, setIndex] = useState<number | null>(null)

<Button onClick={() => setIndex(0)}>Ver as fotos</Button>
<ImageViewer images={fotos} thumbnails={false} index={index} onIndexChange={setIndex} />
```

## Partes

`classNames` alcança cada nó pelo nome: `thumbnails` (a grade), `thumbnail`
(cada botão da grade), `viewer` (a tela cheia), `toolbar` (a barra do alto),
`author` (quem mandou e quando), `counter`, `stage` (a área da imagem), `image`,
`video` (o player do item de vídeo), `caption` e `actions` (a barra de ações).

`labels` troca os textos: `title` (o nome do diálogo, só para o leitor de tela),
`counter` (função da posição e do total), `previous`, `next`, `close`, `zoomIn`,
`zoomOut`, `loading`, `error`, `video` ("Vídeo") e `videoOf`, o vídeo com a
duração falada.

## Quando não usar

- **Um vídeo sozinho, fora de uma galeria**, é `VideoPlayer`, que já abre em
  tela cheia pelo próprio botão. O visualizador é para quando o vídeo vive no
  meio das fotos de uma conversa e a pessoa passa de um para o outro.
- **Conteúdo que não é imagem** é `Dialog`. O visualizador existe para a foto
  ocupar a tela inteira; um formulário ou um texto dentro dele perde o que o
  `Dialog` dá (o título visível, o rodapé de ações, o tamanho que cabe no
  conteúdo).
- **Imagem que só precisa de moldura na página** é `AspectRatio`. Se a pessoa
  não precisa ampliar nem navegar, a foto fica no próprio card, com a proporção
  reservada antes de carregar, e nada abre por cima.
- **Fileira de imagens que se percorre sem ampliar** é `Carousel`. Os dois
  combinam: o carrossel mostra, e o visualizador amplia quando a pessoa pede.

## No React Native

Traduz sobre o `Modal` do core, com as imagens numa `FlatList` horizontal com `pagingEnabled`: deslizar troca de imagem, e o voltar do Android fecha. A grade de miniaturas é a mesma, montada no `Grid` nativo, e cada miniatura é um `imagebutton` com o `alt` como nome. O `index` é controlado, como em todo o pacote nativo: `onIndexChange` recebe o índice ao abrir e ao navegar, e `null` ao fechar.

**A pinça sai do `PanResponder` do core, e não do react-native-gesture-handler.** O pacote já exige o reanimated, mas não o gesture-handler, e um visualizador de imagem não justifica um peer obrigatório a mais para todo app. Dois dedos aproximam até `maxZoom`, um dedo arrasta a foto aproximada, e o toque duplo dobra e desfaz o zoom. Com zoom, a fileira para de rolar: o dedo que arrasta a foto não troca de foto. Os botões de mais, menos, anterior e próximo continuam lá, porque o leitor de tela não faz pinça.

**Arrastar para baixo fecha**, como na galeria do celular: a foto segue o dedo e o fundo esmaece; passou de 120pt, ou soltou rápido, fecha, e senão volta para o lugar. Só com o zoom normal: com zoom, o mesmo arrasto anda pela foto. Com reduzir movimento, a foto não acompanha o dedo, e o arrasto longo fecha do mesmo jeito. O xis continua no alto, para quem não descobre o gesto e para o leitor de tela.

**No chat**, `author` e `date` em cada imagem põem quem mandou e quando no alto, com o contador perto do xis, e `actions` desenha a barra de ações embaixo, como no web. O palco é escuro nos dois esquemas e o celular não tem variável de cor viva para a barra redefinir: pinte o que vai nela com `tokens.media`, como os controles da peça.

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

const INK = { color: tokens.media['media-fg'] }

<ImageViewer
  images={fotos}
  index={index}
  onIndexChange={setIndex}
  thumbnails={false}
  actions={(foto, posicao) => (
    <>
      <Button variant="ghost" onPress={() => responder(posicao)}>
        <Text style={INK}>Responder</Text>
      </Button>
      <Button variant="ghost" onPress={() => encaminhar(posicao)}>
        <Text style={INK}>Encaminhar</Text>
      </Button>
    </>
  )}
/>
```

**Foto e vídeo no mesmo visualizador.** O item com `kind: "video"` entra no meio das fotos, como no web, mas quem toca é o `renderVideo`: o `expo-video` é peer opcional e mora em `@rivocode/ui-native/video`, e a raiz não o importa. De lá sai pronto o `renderViewerVideo`, que monta o `VideoPlayer` com o quadro do tamanho do palco e leva os `headers` do `src` ao `expo-video`. O player só existe no item aberto: o vizinho mostra a capa (`poster`) com o play, e sair do item tira o player de cena, com o vídeo junto. No vídeo não há zoom nem pinça, e arrastar para baixo continua fechando. Sem `renderVideo`, o item fica na capa, e o modo de desenvolvimento avisa.

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

<ImageViewer
  images={midia}
  index={index}
  onIndexChange={setIndex}
  thumbnails={false}
  renderVideo={renderViewerVideo}
/>
```

**Baixar salva na galeria pelo `saveToGallery`.** O `download` liga o botão ao lado do zoom, como no web, mas aqui ele é só a função: salvar na galeria pede o `expo-media-library` e o `expo-file-system`, peers opcionais que moram em `@rivocode/ui-native/media-library`, e a raiz não os importa. O `saveToGallery` de lá pede a permissão de escrita, baixa o arquivo para o cache com os `headers` do `src`, salva na galeria e apaga o cache; cada falha sai como `GalleryError`, com `reason` `unavailable`, `permission`, `download` ou `save`. O `unavailable` é o Expo Go no Android, que não dá acesso à galeria: ali o `saveToGallery` só roda num build de desenvolvimento; no iOS o Expo Go tem o módulo. Enquanto a promessa corre, o botão gira e diz "Baixando…"; a resolvida mostra e anuncia `labels.downloaded` ("Arquivo salvo."), e a rejeitada, `labels.downloadError`. O padrão dele lê o `reason` do `GalleryError` e diz o motivo: no `unavailable`, "Baixar não funciona no Expo Go do Android: use um build de desenvolvimento."; no `permission`, que falta a permissão da galeria; no `download`, que a conexão falhou; no `save`, que a galeria recusou. Ele aceita também a função do erro, `(erro) => string`, para o app dizer o motivo dele. `downloaded: ""` cala o sucesso, para o app que prefere um toast: o `useToast` aparece por cima do visualizador aberto.

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

<ImageViewer
  images={midia}
  index={index}
  onIndexChange={setIndex}
  download={async (item) => {
    await saveToGallery(item.src, { name: item.alt, kind: item.kind })
    toast.add({ title: 'Salvo na galeria', type: 'success' })
  }}
/>
```

`caption` é `string`, a vizinha de cada lado é pedida antes por `Image.prefetch`, e o contador "3 de 8" fica numa região viva que diz também o `alt` da imagem nova.

**SVG entra pelo `renderImage`.** O `Image` do core não decodifica SVG no iOS ("Error decoding image data"), e a peça não decide como desenhar o arquivo: quem tem SVG desenha com o que já usa, na miniatura e no palco, e devolve `undefined` para a foto comum continuar no `Image`. O zoom, o arrasto e o `alt` ficam na moldura de fora; no palco, chame `onLoad` e `onError`, ou o giro não sai.

**Imagem que pede cabeçalho baixa pela peça.** O `src` (e o `thumbnail`) aceita `{ uri, headers }`, como o `VideoPlayer` e o `AudioPlayer`. O `Image` do core **ignora os `headers` da fonte no Android** (a API responde 401 em toda foto), então com `headers` a peça baixa ela mesma por `fetch` e desenha um `data:` URI, com o giro enquanto baixa e o aviso de erro se a resposta não for 2xx. Cada endereço baixa uma vez só enquanto a peça vive, e o `renderImage` recebe o `uri` final, já baixado. Sem `headers`, nada muda.

```tsx
const fotos = mensagens.map((m) => ({
  src: { uri: m.fotoUrl, headers: { 'x-api-key': chave } },
  alt: m.descricao,
}))
```

```tsx
import { SvgUri } from 'react-native-svg'

<ImageViewer
  images={plantas}
  index={index}
  onIndexChange={setIndex}
  renderImage={({ uri, width, height, onLoad, onError }) =>
    uri.endsWith('.svg') ? (
      <SvgUri uri={uri} width={width ?? '100%'} height={height ?? '100%'} onLoad={onLoad} onError={onError} />
    ) : undefined
  }
/>
```

O palco é escuro nos dois esquemas, como no web: as cores saem de `tokens.media`, e não do tema, então o `Modal` não clareia no tema claro nem no tema de cliente. O controle desabilitado segue a regra do pacote, a camada inteira a 50%.

As partes vestem pelo mesmo `classNames` do web, as onze: `thumbnails`, `thumbnail`, `viewer`, `toolbar`, `author`, `counter`, `stage`, `image`, `video`, `caption` e `actions`. O `className` veste a grade de miniaturas, o mesmo nó de `thumbnails`, porque a peça não tem raiz: a grade e o `Modal` são irmãos.

**No iOS e no Android.** A peça cobre a tela inteira, por cima da barra de status e da de navegação, e mede a área segura do aparelho com o `react-native-safe-area-context`, o mesmo número nos dois, e não a da tela, que a navegação zera embaixo do cabeçalho. No Android, o voltar do sistema fecha a peça. O iOS não tem voltar: fecha-se pelo botão da peça ou pelo gesto de escape do VoiceOver, o Z com dois dedos, que chama o mesmo fechar. Ao chegar no fim da rolagem, o iOS estica com mola e o Android estica a borda (Android 12 ou mais novo) ou mostra o brilho (até o 11). É o gesto do sistema, e a peça não o troca. 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 { ImageViewer } from '@rivocode/ui'
```

## Exemplos

### Grade de miniaturas

```tsx
import { Button, ImageViewer, type ImageViewerImage } from '@rivocode/ui'
import { useState } from 'react'

function photo(hue: number, title: string) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="800" viewBox="0 0 1200 800">
    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0" stop-color="hsl(${hue} 45% 62%)"/>
      <stop offset="1" stop-color="hsl(${hue + 40} 50% 28%)"/>
    </linearGradient></defs>
    <rect width="1200" height="800" fill="url(#g)"/>
    <circle cx="900" cy="220" r="110" fill="hsl(${hue + 20} 70% 85%)" opacity="0.7"/>
    <path d="M0 640 L320 380 L560 580 L780 420 L1200 700 L1200 800 L0 800 Z" fill="hsl(${hue + 60} 35% 18%)"/>
    <text x="60" y="110" font-family="sans-serif" font-size="56" fill="white">${title}</text>
  </svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

const PHOTOS: ImageViewerImage[] = [
  { src: photo(200, 'Fachada'), alt: 'Fachada do prédio comercial', caption: 'Fachada, vista da avenida' },
  { src: photo(30, 'Recepção'), alt: 'Recepção com balcão de madeira', caption: 'Recepção no térreo' },
  { src: photo(140, 'Sala 1'), alt: 'Sala de reunião com mesa para oito pessoas' },
  { src: photo(260, 'Sala 2'), alt: 'Sala de trabalho com seis estações' },
  { src: photo(330, 'Copa'), alt: 'Copa com geladeira e micro-ondas', caption: 'Copa compartilhada' },
  { src: photo(90, 'Terraço'), alt: 'Terraço com vista para o parque' },
]

export function Gallery() {
  return <ImageViewer images={PHOTOS} className="max-w-xl" />
}
```

### Em volta, da última volta à primeira

```tsx
import { Button, ImageViewer, type ImageViewerImage } from '@rivocode/ui'
import { useState } from 'react'

function photo(hue: number, title: string) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="800" viewBox="0 0 1200 800">
    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0" stop-color="hsl(${hue} 45% 62%)"/>
      <stop offset="1" stop-color="hsl(${hue + 40} 50% 28%)"/>
    </linearGradient></defs>
    <rect width="1200" height="800" fill="url(#g)"/>
    <circle cx="900" cy="220" r="110" fill="hsl(${hue + 20} 70% 85%)" opacity="0.7"/>
    <path d="M0 640 L320 380 L560 580 L780 420 L1200 700 L1200 800 L0 800 Z" fill="hsl(${hue + 60} 35% 18%)"/>
    <text x="60" y="110" font-family="sans-serif" font-size="56" fill="white">${title}</text>
  </svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

const PHOTOS: ImageViewerImage[] = [
  { src: photo(200, 'Fachada'), alt: 'Fachada do prédio comercial', caption: 'Fachada, vista da avenida' },
  { src: photo(30, 'Recepção'), alt: 'Recepção com balcão de madeira', caption: 'Recepção no térreo' },
  { src: photo(140, 'Sala 1'), alt: 'Sala de reunião com mesa para oito pessoas' },
  { src: photo(260, 'Sala 2'), alt: 'Sala de trabalho com seis estações' },
  { src: photo(330, 'Copa'), alt: 'Copa com geladeira e micro-ondas', caption: 'Copa compartilhada' },
  { src: photo(90, 'Terraço'), alt: 'Terraço com vista para o parque' },
]

export function Looping() {
  return <ImageViewer images={PHOTOS.slice(0, 3)} loop className="max-w-xs" />
}
```

### Controlado, aberto por outro botão

```tsx
import { Button, ImageViewer, type ImageViewerImage } from '@rivocode/ui'
import { useState } from 'react'

function photo(hue: number, title: string) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="800" viewBox="0 0 1200 800">
    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0" stop-color="hsl(${hue} 45% 62%)"/>
      <stop offset="1" stop-color="hsl(${hue + 40} 50% 28%)"/>
    </linearGradient></defs>
    <rect width="1200" height="800" fill="url(#g)"/>
    <circle cx="900" cy="220" r="110" fill="hsl(${hue + 20} 70% 85%)" opacity="0.7"/>
    <path d="M0 640 L320 380 L560 580 L780 420 L1200 700 L1200 800 L0 800 Z" fill="hsl(${hue + 60} 35% 18%)"/>
    <text x="60" y="110" font-family="sans-serif" font-size="56" fill="white">${title}</text>
  </svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

const PHOTOS: ImageViewerImage[] = [
  { src: photo(200, 'Fachada'), alt: 'Fachada do prédio comercial', caption: 'Fachada, vista da avenida' },
  { src: photo(30, 'Recepção'), alt: 'Recepção com balcão de madeira', caption: 'Recepção no térreo' },
  { src: photo(140, 'Sala 1'), alt: 'Sala de reunião com mesa para oito pessoas' },
  { src: photo(260, 'Sala 2'), alt: 'Sala de trabalho com seis estações' },
  { src: photo(330, 'Copa'), alt: 'Copa com geladeira e micro-ondas', caption: 'Copa compartilhada' },
  { src: photo(90, 'Terraço'), alt: 'Terraço com vista para o parque' },
]

const SENT: ImageViewerImage[] = PHOTOS.slice(0, 4).map((image, position) => ({
  ...image,
  author: position % 2 === 0 ? 'Marina Costa' : 'Você',
  date: `hoje, 14:${30 + position}`,
}))

export function Controlled() {
  const [index, setIndex] = useState<number | null>(null)

  return (
    <div className="flex items-center gap-3">
      <Button variant="secondary" onClick={() => setIndex(0)}>
        Ver as {PHOTOS.length} fotos
      </Button>
      <ImageViewer
        images={PHOTOS}
        thumbnails={false}
        index={index}
        onIndexChange={setIndex}
      />
    </div>
  )
}

const SENT: ImageViewerImage[] = PHOTOS.slice(0, 4).map((image, position) => ({
  ...image,
  author: position % 2 === 0 ? 'Marina Costa' : 'Você',
  date: `hoje, 14:${30 + position}`,
}))
```

### No chat, com quem mandou e a barra de ações

```tsx
import { Button, ImageViewer, type ImageViewerImage } from '@rivocode/ui'
import { useState } from 'react'

function photo(hue: number, title: string) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="800" viewBox="0 0 1200 800">
    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0" stop-color="hsl(${hue} 45% 62%)"/>
      <stop offset="1" stop-color="hsl(${hue + 40} 50% 28%)"/>
    </linearGradient></defs>
    <rect width="1200" height="800" fill="url(#g)"/>
    <circle cx="900" cy="220" r="110" fill="hsl(${hue + 20} 70% 85%)" opacity="0.7"/>
    <path d="M0 640 L320 380 L560 580 L780 420 L1200 700 L1200 800 L0 800 Z" fill="hsl(${hue + 60} 35% 18%)"/>
    <text x="60" y="110" font-family="sans-serif" font-size="56" fill="white">${title}</text>
  </svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

const PHOTOS: ImageViewerImage[] = [
  { src: photo(200, 'Fachada'), alt: 'Fachada do prédio comercial', caption: 'Fachada, vista da avenida' },
  { src: photo(30, 'Recepção'), alt: 'Recepção com balcão de madeira', caption: 'Recepção no térreo' },
  { src: photo(140, 'Sala 1'), alt: 'Sala de reunião com mesa para oito pessoas' },
  { src: photo(260, 'Sala 2'), alt: 'Sala de trabalho com seis estações' },
  { src: photo(330, 'Copa'), alt: 'Copa com geladeira e micro-ondas', caption: 'Copa compartilhada' },
  { src: photo(90, 'Terraço'), alt: 'Terraço com vista para o parque' },
]

const SENT: ImageViewerImage[] = PHOTOS.slice(0, 4).map((image, position) => ({
  ...image,
  author: position % 2 === 0 ? 'Marina Costa' : 'Você',
  date: `hoje, 14:${30 + position}`,
}))

const MEDIA: ImageViewerImage[] = [
  { ...SENT[0]!, author: 'Marina Costa', date: 'hoje, 14:30' },
  {
    src: 'https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4',
    alt: '',
    kind: 'video',
    poster: photo(320, 'Vídeo'),
    duration: 5,
    author: 'Marina Costa',
    date: 'hoje, 14:31',
  },
  { ...SENT[1]!, author: 'Você', date: 'hoje, 14:32' },
]

export function ChatViewer() {
  const [index, setIndex] = useState<number | null>(null)
  const [done, setDone] = useState('')

  return (
    <div className="flex flex-col items-start gap-3">
      <Button variant="secondary" onClick={() => setIndex(0)}>
        Abrir as fotos da conversa
      </Button>
      {done && <p className="text-sm text-fg-muted">{done}</p>}
      <ImageViewer
        images={SENT}
        thumbnails={false}
        index={index}
        onIndexChange={setIndex}
        download
        actions={(image, position) => (
          <>
            <Button variant="ghost" onClick={() => setDone(`Respondendo a foto ${position + 1}`)}>
              Responder
            </Button>
            <Button variant="ghost" onClick={() => setDone(`Encaminhando: ${image.alt}`)}>
              Encaminhar
            </Button>
          </>
        )}
      />
    </div>
  )
}

const MEDIA: ImageViewerImage[] = [
  { ...SENT[0]!, author: 'Marina Costa', date: 'hoje, 14:30' },
  {
    src: 'https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4',
    alt: '',
    kind: 'video',
    poster: photo(320, 'Vídeo'),
    duration: 5,
    author: 'Marina Costa',
    date: 'hoje, 14:31',
  },
  { ...SENT[1]!, author: 'Você', date: 'hoje, 14:32' },
]
```

### Foto e vídeo da conversa no mesmo visualizador

```tsx
import { Button, ImageViewer, type ImageViewerImage } from '@rivocode/ui'
import { useState } from 'react'

function photo(hue: number, title: string) {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="800" viewBox="0 0 1200 800">
    <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0" stop-color="hsl(${hue} 45% 62%)"/>
      <stop offset="1" stop-color="hsl(${hue + 40} 50% 28%)"/>
    </linearGradient></defs>
    <rect width="1200" height="800" fill="url(#g)"/>
    <circle cx="900" cy="220" r="110" fill="hsl(${hue + 20} 70% 85%)" opacity="0.7"/>
    <path d="M0 640 L320 380 L560 580 L780 420 L1200 700 L1200 800 L0 800 Z" fill="hsl(${hue + 60} 35% 18%)"/>
    <text x="60" y="110" font-family="sans-serif" font-size="56" fill="white">${title}</text>
  </svg>`
  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`
}

const PHOTOS: ImageViewerImage[] = [
  { src: photo(200, 'Fachada'), alt: 'Fachada do prédio comercial', caption: 'Fachada, vista da avenida' },
  { src: photo(30, 'Recepção'), alt: 'Recepção com balcão de madeira', caption: 'Recepção no térreo' },
  { src: photo(140, 'Sala 1'), alt: 'Sala de reunião com mesa para oito pessoas' },
  { src: photo(260, 'Sala 2'), alt: 'Sala de trabalho com seis estações' },
  { src: photo(330, 'Copa'), alt: 'Copa com geladeira e micro-ondas', caption: 'Copa compartilhada' },
  { src: photo(90, 'Terraço'), alt: 'Terraço com vista para o parque' },
]

const SENT: ImageViewerImage[] = PHOTOS.slice(0, 4).map((image, position) => ({
  ...image,
  author: position % 2 === 0 ? 'Marina Costa' : 'Você',
  date: `hoje, 14:${30 + position}`,
}))

const MEDIA: ImageViewerImage[] = [
  { ...SENT[0]!, author: 'Marina Costa', date: 'hoje, 14:30' },
  {
    src: 'https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4',
    alt: '',
    kind: 'video',
    poster: photo(320, 'Vídeo'),
    duration: 5,
    author: 'Marina Costa',
    date: 'hoje, 14:31',
  },
  { ...SENT[1]!, author: 'Você', date: 'hoje, 14:32' },
]

export function ChatMedia() {
  return <ImageViewer images={MEDIA} className="max-w-sm" />
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `images` | `ImageViewerImage[]` | sim |  | - | As imagens, na ordem da navegacao. |
| `actions` | `((image: ImageViewerImage, index: number) => ReactNode)` |  |  | - | A barra de acoes embaixo da imagem aberta, que o app escolhe: Responder, Encaminhar, Salvar. |
| `classNames` | `Partial<Record<"actions" \| "author" \| "caption" \| "counter" \| "image" \| "stage" \| "thumbnail" \| "thumbnails" \| "toolbar" \| "video" \| "viewer", string>>` |  |  | - | Classe por parte: `thumbnails`, `thumbnail`, `viewer`, `toolbar`, `author` (quem mandou e quando), `counter`, `stage`, `image`, `video` (o player do item de video), `caption` e `actions`. |
| `defaultIndex` | `number \| null` |  | `null` | - | A imagem aberta ao montar, quando ninguem controla. |
| `download` | `boolean \| ((image: ImageViewerImage, index: number) => void \| Promise<unknown>)` |  |  | - | Liga o botao Baixar na barra de cima, ao lado do zoom. |
| `index` | `number \| null` |  |  | - | A imagem aberta, controlada: o indice, contando de zero, ou `null` com o visualizador fechado. |
| `labels` | `Partial<ImageViewerLabels>` |  |  | - | Os textos da peca, para trocar o idioma ou o termo. |
| `loop` | `boolean` |  | `false` | - | Da ultima, a proxima volta a primeira, e vice-versa. |
| `maxZoom` | `number` |  | `4` | - | O zoom maximo, em vezes o tamanho que cabe na tela. |
| `onIndexChange` | `((index: number \| null) => void)` |  |  | - | Chamado ao abrir, ao navegar e com `null` ao fechar. |
| `thumbnails` | `boolean` |  | `true` | - | Desenha a grade de miniaturas que abre o visualizador. |

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

## Ver também

- [AlertDialog](/componentes/alert-dialog.md)
- [ContextMenu](/componentes/context-menu.md)
- [Dialog](/componentes/dialog.md)
- [Popconfirm](/componentes/popconfirm.md)
- [Popover](/componentes/popover.md)
- [PreviewCard](/componentes/preview-card.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
