# ChartFunnel

As etapas de um caminho, com quantos chegaram a cada uma e quantos passaram de
uma para a seguinte: de quem visitou a quem assinou um plano.

```tsx
<ChartFunnel
  data={adesao}
  valueKey="total"
  nameKey="etapa"
  format="integer"
  label="Funil de adesão em agosto"
/>
```

Cada etapa tem o nome, o número e uma barra com largura proporcional à etapa
mais larga. Entre duas etapas vem a **taxa de conversão**, escrita: "↓ 25%
da etapa anterior". No fim, a conversão de ponta a ponta. A taxa é a informação
que o desenho de funil sozinho não dá, porque o olho compara largura e não
razão, e é quase sempre a pergunta de quem abriu o painel.

## A conta

A taxa é a etapa sobre a anterior, e a de ponta a ponta é a última sobre a
primeira. Etapa anterior zerada não inventa taxa: aparece "—". `formatRate`
troca a escrita, e recebe de 0 a 100. `labels.rate` e `labels.overall` trocam
as frases, que é o que um produto em outra língua precisa; `showOverall={false}`
esconde a linha do total.

## O desenho

`align="center"` desenha o funil de verdade, cada barra centrada sob a de cima.
`align="start"` alinha as barras à esquerda, que lê melhor quando os nomes são
longos e o que importa é comparar comprimento.

Todas as barras têm a mesma cor, `var(--rc-chart-1)` ou a do `color`, e isso é
de propósito: as etapas não são categorias diferentes, são a mesma população
encolhendo, e uma cor por etapa sugeriria o contrário.

## Leitor de tela

Não há desenho para descrever: a peça **é** uma lista ordenada, com o nome de
cada etapa, o número e a taxa em texto, e a barra fica escondida dele. `label`
dá nome à lista.

## Movimento

As barras crescem do centro (ou da esquerda, no `start`) na primeira vez, e
andam até a largura nova quando os dados mudam, em `--rc-duration-slow`. Com
"reduzir movimento", nascem no lugar.

## Sem dado

`empty` é o mesmo objeto do `ChartContainer` e do `DataTable`: `title`,
`description` obrigatória, `action` e `icon` opcionais. Ele aparece no lugar do
desenho quando a lista vem vazia ou todas as etapas somam zero. Sem ele, o funil desenha as etapas com barra de largura zero.

## Quando não usar

Quando as etapas não são um subconjunto uma da outra (canais de aquisição,
categorias de produto), não há conversão para calcular, e o que existe é
comparação: barra deitada. Quando o assunto é **onde a pessoa está** num
processo, e não quantas passaram, é o `Steps`, que olha para a frente. E para
dizer que parte do total é de cada coisa, é o `ChartDonut`: fatia é parte de um
todo, e etapa de funil não é.

## No React Native

Traduz, em `@rivocode/ui-native/chart`, e é a peça de gráfico que menos precisa do `react-native-svg`: as barras são `View`, e a conta das taxas é a mesma função do web, gerada em `native/src/shared/`. `valueKey`, `nameKey`, `align`, `formatRate`, `showOverall`, `labels` e `format`, com nome de formatador ou função, atravessam iguais.

Uma mudança de tipo, a mesma da rosca: `color` é papel de token (`chart-2`) e não cor de CSS. E uma de leitura: no web a peça é uma lista ordenada e o leitor de tela lê o nome, o número e a taxa em pedaços; aqui **cada etapa é uma parada só**, com os três na mesma frase ("Cadastros: 400, 40% da etapa anterior"), porque o leitor de tela do celular anda de elemento em elemento e três paradas por etapa triplicariam o caminho. Não há `label`: no toque não existe nome de lista, e o título do cartão faz esse papel.

As barras crescem do zero ao aparecer e andam até a largura nova quando os dados mudam, pelo Reanimated e com os tokens de movimento; com "reduzir movimento", nascem no lugar.

As partes vestem pelo mesmo `classNames` do web: `stage`, `bar` e `rate`. Com `empty` (o formato do `ChartContainer`), lista vazia ou soma zero mostram o estado vazio no lugar das barras.

## Importação

```tsx
import { ChartFunnel } from '@rivocode/ui/chart'
```

## Exemplos

### Funil de adesão

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@rivocode/ui'
import { ChartFunnel } from '@rivocode/ui/chart'

const ONBOARDING = [
  { stage: 'Visitaram a página de preços', total: 12_480 },
  { stage: 'Criaram conta', total: 3_120 },
  { stage: 'Convidaram a equipe', total: 1_406 },
  { stage: 'Assinaram um plano', total: 988 },
]

const COLLECTION = [
  { stage: 'Boletos emitidos', total: 486_200 },
  { stage: 'Boletos vistos', total: 412_900 },
  { stage: 'Boletos pagos', total: 371_300 },
]

export function Onboarding() {
  return (
    <Card className="w-full max-w-96">
      <CardHeader>
        <CardTitle>Adesão em agosto</CardTitle>
        <CardDescription>De quem chegou a quem assinou.</CardDescription>
      </CardHeader>
      <CardContent>
        <ChartFunnel
          data={ONBOARDING}
          valueKey="total"
          nameKey="stage"
          format="integer"
          label="Funil de adesão em agosto"
        />
      </CardContent>
    </Card>
  )
}

const COLLECTION = [
  { stage: 'Boletos emitidos', total: 486_200 },
  { stage: 'Boletos vistos', total: 412_900 },
  { stage: 'Boletos pagos', total: 371_300 },
]
```

### Alinhado à esquerda, em dinheiro

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@rivocode/ui'
import { ChartFunnel } from '@rivocode/ui/chart'

const COLLECTION = [
  { stage: 'Boletos emitidos', total: 486_200 },
  { stage: 'Boletos vistos', total: 412_900 },
  { stage: 'Boletos pagos', total: 371_300 },
]

export function AlignedToStart() {
  return (
    <div className="w-full max-w-80">
      <ChartFunnel
        data={COLLECTION}
        valueKey="total"
        nameKey="stage"
        format="currencyShort"
        align="start"
        color="var(--rc-chart-2)"
        label="Cobrança do mês, em reais"
      />
    </div>
  )
}
```

### Sem etapa nenhuma

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@rivocode/ui'
import { ChartFunnel } from '@rivocode/ui/chart'

const ONBOARDING = [
  { stage: 'Visitaram a página de preços', total: 12_480 },
  { stage: 'Criaram conta', total: 3_120 },
  { stage: 'Convidaram a equipe', total: 1_406 },
  { stage: 'Assinaram um plano', total: 988 },
]

export function EmptyFunnel() {
  return (
    <div className="w-full max-w-md">
      <ChartFunnel
        data={[] as typeof ONBOARDING}
        valueKey="total"
        nameKey="stage"
        label="Funil de adesão"
        empty={{
          title: 'Ninguém entrou no funil ainda',
          description: 'As etapas aparecem quando a primeira visita for registrada.',
        }}
      />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `data` | `Stage[]` | sim |  | - | As etapas, na ordem em que a pessoa atravessa: a primeira e a boca do funil. |
| `nameKey` | `keyof Stage & string` | sim |  | - | De onde sai o nome de cada etapa. |
| `valueKey` | `keyof Stage & string` | sim |  | - | De onde sai o numero de cada etapa. |
| `align` | `"center" \| "start"` |  | `"center"` | - | `center` desenha o funil de verdade, cada barra centrada sob a anterior; `start` alinha as barras a esquerda, que le melhor quando os nomes sao longos e o olho compara comprimento. |
| `classNames` | `Partial<Record<"bar" \| "rate" \| "stage", string>>` |  |  | - | Classe por parte: `stage`, `bar`, `rate`. |
| `color` | `string` |  | `"var(--rc-chart-1)"` | - | A cor das barras. |
| `empty` | `{ title: ReactNode; description: ReactNode; action?: ReactNode; icon?: ReactNode; }` |  |  | - | O que aparece no lugar do desenho quando a lista vem vazia ou todas as etapas somam zero. |
| `format` | `Format` |  |  | - | Como o numero de cada etapa e escrito. |
| `formatRate` | `((rate: number) => string)` |  |  | - | Como a taxa e escrita, recebendo de 0 a 100. |
| `label` | `string` |  |  | - | O nome da lista para o leitor de tela: "Funil de vendas do mes". |
| `labels` | `Partial<ChartFunnelLabels>` |  |  | - | Os textos da peca, para trocar o idioma: `rate` e o que vem depois da taxa entre duas etapas, "da etapa anterior" sem ele, e `overall` a frase da conversao de ponta a ponta, "do inicio ao fim" sem ela. |
| `showOverall` | `boolean` |  | `true` | - | Mostra a linha da conversao de ponta a ponta, embaixo. |

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

## Ver também

- [ChartContainer](/componentes/chart-container.md)
- [ChartDonut](/componentes/chart-donut.md)
- [ChartGauge](/componentes/chart-gauge.md)
- [ChartHeatmap](/componentes/chart-heatmap.md)
- [ChartRadial](/componentes/chart-radial.md)
- [ChartTreemap](/componentes/chart-treemap.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
