# Data Overlay

Card compacto para KPI, contexto de mapa ou widget de monitoramento.

> Documentação do Sinapse DS. Snippets shadcn usam os componentes do seu projeto (`@/components/ui/*`); snippets HTML usam as classes `itps-*` do CSS Sinapse (`/css/<versão>/`, veja `/comecar.md`). Componentes do site de documentação não fazem parte do DS.

- Categoria: Data Display
- Status: stable

## Em cada stack

- HTML e Astro: Classes `itps-*` do CSS Sinapse, com todas as variantes desta página.
- React e Vue: Componente Sinapse, com as variantes desta página (`add @sinapse/data-overlay`).

**React/Next (shadcn/ui)**

```tsx
import { IconArrowDown } from '@tabler/icons-react'

import {
  DataOverlay,
  DataOverlayBody,
  DataOverlayCurrent,
  DataOverlayDescription,
  DataOverlayHeader,
  DataOverlayHeading,
  DataOverlayLabel,
  DataOverlayNumber,
  DataOverlayTitle,
  DataOverlayValue,
} from '@/components/ui/data-overlay'
import { Tag } from '@/components/ui/tag'

export function DataOverlayExample() {
  return (
    <DataOverlay aria-labelledby="overlay-atendimentos">
      <DataOverlayHeader>
        <DataOverlayHeading>
          <DataOverlayTitle id="overlay-atendimentos">Atendimentos</DataOverlayTitle>
          <DataOverlayDescription>Última hora</DataOverlayDescription>
        </DataOverlayHeading>
        <Tag variant="success">estável</Tag>
      </DataOverlayHeader>
      <DataOverlayCurrent>
        <DataOverlayLabel>Atual</DataOverlayLabel>
        <DataOverlayValue>
          <IconArrowDown aria-hidden="true" />
          <span className="sr-only">tendência de baixa</span>
          <DataOverlayNumber>128</DataOverlayNumber>
        </DataOverlayValue>
      </DataOverlayCurrent>
      <DataOverlayBody>
        <p className="text-sm leading-normal text-muted-foreground">
          Movimento dentro do esperado para a região monitorada.
        </p>
      </DataOverlayBody>
    </DataOverlay>
  )
}
```

**Vue 3/Nuxt 4 (shadcn-vue)**

```vue
<script setup lang="ts">
import { IconArrowDown } from '@tabler/icons-vue'

import {
  DataOverlay,
  DataOverlayBody,
  DataOverlayCurrent,
  DataOverlayDescription,
  DataOverlayHeader,
  DataOverlayHeading,
  DataOverlayLabel,
  DataOverlayNumber,
  DataOverlayTitle,
  DataOverlayValue,
} from '@/components/ui/data-overlay'
import { Tag } from '@/components/ui/tag'
</script>

<template>
  <DataOverlay aria-labelledby="overlay-atendimentos">
    <DataOverlayHeader>
      <DataOverlayHeading>
        <DataOverlayTitle id="overlay-atendimentos">Atendimentos</DataOverlayTitle>
        <DataOverlayDescription>Última hora</DataOverlayDescription>
      </DataOverlayHeading>
      <Tag variant="success">estável</Tag>
    </DataOverlayHeader>
    <DataOverlayCurrent>
      <DataOverlayLabel>Atual</DataOverlayLabel>
      <DataOverlayValue>
        <IconArrowDown aria-hidden="true" />
        <span class="sr-only">tendência de baixa</span>
        <DataOverlayNumber>128</DataOverlayNumber>
      </DataOverlayValue>
    </DataOverlayCurrent>
    <DataOverlayBody>
      <p class="text-sm leading-normal text-muted-foreground">
        Movimento dentro do esperado para a região monitorada.
      </p>
    </DataOverlayBody>
  </DataOverlay>
</template>
```

**HTML (copy-first)**

```html
<article class="itps-data-overlay" aria-labelledby="overlay-atendimentos">
  <header class="itps-data-overlay__header">
    <div class="itps-data-overlay__heading">
      <h3 id="overlay-atendimentos" class="itps-data-overlay__title">Atendimentos</h3>
      <p class="itps-data-overlay__description">Última hora</p>
    </div>
    <span class="itps-tag itps-tag--success itps-tag--sm">estável</span>
  </header>
  <div class="itps-data-overlay__current">
    <span class="itps-data-overlay__label">Atual</span>
    <span class="itps-data-overlay__value">
      <i class="itps-data-overlay__trend ti ti-arrow-down" aria-hidden="true"></i>
      <span class="sr-only">tendência de baixa</span>
      <span class="itps-data-overlay__number">128</span>
    </span>
  </div>
  <div class="itps-data-overlay__body">
    <p class="text-sm leading-normal text-muted-foreground">
      Movimento dentro do esperado para a região monitorada.
    </p>
  </div>
</article>
```

## Instalação

O comando instala o componente `DataOverlay` do Sinapse, com as variantes `alert` e `danger` e o pin, e a `Tag` usada no cabeçalho. Não é o Card do shadcn. Configure o registry uma vez por projeto em [Comece por aqui](/comecar).

**terminal · React/Next**

```sh
pnpm dlx shadcn@latest add @sinapse/data-overlay
```

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/data-overlay.json
```

Sem shadcn, não há instalação por componente: use o CSS Sinapse e as classes da API copy-first desta página.

## Uso

Em React/Next com shadcn/ui e Vue 3/Nuxt 4 com shadcn-vue, use `DataOverlay` e suas partes, com `Tag` para o estado. As partes leem a severidade (`variant`) da raiz, então basta definir a variante uma vez.

Para HTML ou wrappers finos, use `itps-data-overlay` quando o overlay precisa ficar sobre um mapa, painel lateral ou widget de monitoramento. Mantenha a estrutura pública para que o CSS do pacote resolva espaçamento, status e pin.

A largura padrão é de 320 px, pensada para o overlay sobre mapa. Numa grade de indicadores, deixe o card ocupar a coluna: `className="w-full max-w-none"` em React e Vue, ou as mesmas classes junto de `itps-data-overlay` em HTML. O título quebra em até duas linhas.

## Exemplos

### Estrutura

| Peça | React/Next e Vue 3/Nuxt 4 | HTML |
|------|--------------------------|------|
| Superfície | `DataOverlay` | `itps-data-overlay` |
| Severidade | `variant`: `default`, `alert`, `danger` | `itps-data-overlay--alert`, `itps-data-overlay--danger` |
| Cabeçalho | `DataOverlayHeader` + `DataOverlayHeading` | `itps-data-overlay__header` + `itps-data-overlay__heading` |
| Título | `DataOverlayTitle` | `itps-data-overlay__title` |
| Descrição | `DataOverlayDescription` | `itps-data-overlay__description` |
| Estado | `Tag` | `itps-tag` |
| KPI atual | `DataOverlayCurrent`, `DataOverlayLabel`, `DataOverlayValue`, `DataOverlayNumber` | `itps-data-overlay__current`, `__label`, `__value`, `__number` |
| Corpo | `DataOverlayBody` | `itps-data-overlay__body` |
| Pin | `DataOverlayPin` | `itps-data-overlay__pin` |

### Estados e pin

Use a severidade no contêiner quando ela muda a leitura do overlay. Combine `variant="alert"` ou `variant="danger"` (no HTML, `itps-data-overlay--alert` ou `itps-data-overlay--danger`) com a Tag equivalente para que a cor nunca seja o único sinal.

**React/Next (shadcn/ui)**

```tsx
import { IconArrowUp } from '@tabler/icons-react'

import {
  DataOverlay,
  DataOverlayBody,
  DataOverlayCurrent,
  DataOverlayDescription,
  DataOverlayHeader,
  DataOverlayHeading,
  DataOverlayLabel,
  DataOverlayNumber,
  DataOverlayPin,
  DataOverlayTitle,
  DataOverlayValue,
} from '@/components/ui/data-overlay'
import { Tag } from '@/components/ui/tag'

export function DataOverlayStates() {
  return (
    <div className="grid w-full gap-4 lg:grid-cols-2">
      <DataOverlay variant="alert" aria-labelledby="overlay-territorio">
        <DataOverlayHeader>
          <DataOverlayHeading>
            <DataOverlayTitle id="overlay-territorio">Território norte</DataOverlayTitle>
            <DataOverlayDescription>Mapa operacional</DataOverlayDescription>
          </DataOverlayHeading>
          <Tag variant="alert">atenção</Tag>
        </DataOverlayHeader>
        <DataOverlayCurrent>
          <DataOverlayLabel>Atual</DataOverlayLabel>
          <DataOverlayValue>
            <IconArrowUp aria-hidden="true" />
            <span className="sr-only">tendência de alta</span>
            <DataOverlayNumber>78</DataOverlayNumber>
          </DataOverlayValue>
        </DataOverlayCurrent>
        <DataOverlayPin />
      </DataOverlay>

      <DataOverlay variant="danger" aria-labelledby="overlay-indicadores">
        <DataOverlayHeader>
          <DataOverlayHeading>
            <DataOverlayTitle id="overlay-indicadores">Indicadores</DataOverlayTitle>
            <DataOverlayDescription>Capital · maio de 2026</DataOverlayDescription>
          </DataOverlayHeading>
          <Tag variant="danger">alto</Tag>
        </DataOverlayHeader>
        <DataOverlayCurrent>
          <DataOverlayLabel>Internações</DataOverlayLabel>
          <DataOverlayValue>
            <IconArrowUp aria-hidden="true" />
            <span className="sr-only">tendência de alta</span>
            <DataOverlayNumber>96</DataOverlayNumber>
          </DataOverlayValue>
        </DataOverlayCurrent>
        <DataOverlayBody>
          <ul className="space-y-1 text-sm leading-normal text-foreground">
            <li>Casos novos: 1.284</li>
            <li>UTIs: 42</li>
            <li>Fila de regulação: 18</li>
          </ul>
        </DataOverlayBody>
      </DataOverlay>
    </div>
  )
}
```

**Vue 3/Nuxt 4 (shadcn-vue)**

```vue
<script setup lang="ts">
import { IconArrowUp } from '@tabler/icons-vue'

import {
  DataOverlay,
  DataOverlayBody,
  DataOverlayCurrent,
  DataOverlayDescription,
  DataOverlayHeader,
  DataOverlayHeading,
  DataOverlayLabel,
  DataOverlayNumber,
  DataOverlayPin,
  DataOverlayTitle,
  DataOverlayValue,
} from '@/components/ui/data-overlay'
import { Tag } from '@/components/ui/tag'
</script>

<template>
  <div class="grid w-full gap-4 lg:grid-cols-2">
    <DataOverlay variant="alert" aria-labelledby="overlay-territorio">
      <DataOverlayHeader>
        <DataOverlayHeading>
          <DataOverlayTitle id="overlay-territorio">Território norte</DataOverlayTitle>
          <DataOverlayDescription>Mapa operacional</DataOverlayDescription>
        </DataOverlayHeading>
        <Tag variant="alert">atenção</Tag>
      </DataOverlayHeader>
      <DataOverlayCurrent>
        <DataOverlayLabel>Atual</DataOverlayLabel>
        <DataOverlayValue>
          <IconArrowUp aria-hidden="true" />
          <span class="sr-only">tendência de alta</span>
          <DataOverlayNumber>78</DataOverlayNumber>
        </DataOverlayValue>
      </DataOverlayCurrent>
      <DataOverlayPin />
    </DataOverlay>

    <DataOverlay variant="danger" aria-labelledby="overlay-indicadores">
      <DataOverlayHeader>
        <DataOverlayHeading>
          <DataOverlayTitle id="overlay-indicadores">Indicadores</DataOverlayTitle>
          <DataOverlayDescription>Capital · maio de 2026</DataOverlayDescription>
        </DataOverlayHeading>
        <Tag variant="danger">alto</Tag>
      </DataOverlayHeader>
      <DataOverlayCurrent>
        <DataOverlayLabel>Internações</DataOverlayLabel>
        <DataOverlayValue>
          <IconArrowUp aria-hidden="true" />
          <span class="sr-only">tendência de alta</span>
          <DataOverlayNumber>96</DataOverlayNumber>
        </DataOverlayValue>
      </DataOverlayCurrent>
      <DataOverlayBody>
        <ul class="space-y-1 text-sm leading-normal text-foreground">
          <li>Casos novos: 1.284</li>
          <li>UTIs: 42</li>
          <li>Fila de regulação: 18</li>
        </ul>
      </DataOverlayBody>
    </DataOverlay>
  </div>
</template>
```

**HTML (copy-first)**

```html
<div class="grid w-full gap-4 lg:grid-cols-2">
  <div class="flex min-h-52 items-center justify-center rounded-lg border border-border bg-secondary/30 p-4 sm:p-8">
    <article class="itps-data-overlay itps-data-overlay--alert" aria-labelledby="overlay-territorio">
      <header class="itps-data-overlay__header">
        <div class="itps-data-overlay__heading">
          <h3 id="overlay-territorio" class="itps-data-overlay__title">Território norte</h3>
          <p class="itps-data-overlay__description">Mapa operacional</p>
        </div>
        <span class="itps-tag itps-tag--alert itps-tag--sm">atenção</span>
      </header>
      <div class="itps-data-overlay__current">
        <span class="itps-data-overlay__label">Atual</span>
        <span class="itps-data-overlay__value">
          <i class="itps-data-overlay__trend ti ti-arrow-up" aria-hidden="true"></i>
          <span class="sr-only">tendência de alta</span>
          <span class="itps-data-overlay__number">78</span>
        </span>
      </div>
      <span class="itps-data-overlay__pin" aria-hidden="true"></span>
    </article>
  </div>

  <article class="itps-data-overlay itps-data-overlay--danger" aria-labelledby="overlay-indicadores">
    <header class="itps-data-overlay__header">
      <div class="itps-data-overlay__heading">
        <h3 id="overlay-indicadores" class="itps-data-overlay__title">Indicadores</h3>
        <p class="itps-data-overlay__description">Capital · maio de 2026</p>
      </div>
      <span class="itps-tag itps-tag--danger itps-tag--sm">alto</span>
    </header>
    <div class="itps-data-overlay__current">
      <span class="itps-data-overlay__label">Internações</span>
      <span class="itps-data-overlay__value">
        <i class="itps-data-overlay__trend ti ti-arrow-up" aria-hidden="true"></i>
        <span class="sr-only">tendência de alta</span>
        <span class="itps-data-overlay__number">96</span>
      </span>
    </div>
    <div class="itps-data-overlay__body">
      <ul class="space-y-1 text-sm leading-normal text-foreground">
        <li>Casos novos: 1.284</li>
        <li>UTIs: 42</li>
        <li>Fila de regulação: 18</li>
      </ul>
    </div>
  </article>
</div>
```

## API copy-first

| Classe/atributo | Uso |
|-----------------|-----|
| `itps-data-overlay` | Superfície compacta para KPI ou widget contextual. |
| `itps-data-overlay--alert` | Estado intermediário de atenção. |
| `itps-data-overlay--danger` | Estado crítico ou de maior severidade. |
| `itps-data-overlay__header` | Agrupa título, descrição e tag. |
| `itps-data-overlay__current` | Linha numérica principal do overlay. |
| `itps-data-overlay__trend` | Ícone decorativo de tendência. |
| `itps-data-overlay__body` | Conteúdo complementar curto. |
| `itps-data-overlay__pin` | Marcador visual para overlays posicionados em mapa. |
| `aria-labelledby` | Liga o `article` ao título visível. |
| `sr-only` | Expõe tendência textual quando a seta é decorativa. |

## Acessibilidade

Use `article` com `aria-labelledby` quando o overlay representa um widget autônomo. A tendência precisa de texto `sr-only`, porque o ícone sozinho não comunica direção para leitores de tela. Quando houver status visual, mantenha também o texto da tag.