# ChartGauge

Um medidor de 0 a `max` com faixas que dizem se o número está bom: em dia,
atenção, crítico. O valor fica escrito no meio, e o nome da faixa embaixo dele.

```tsx
<ChartGauge
  value={8.4}
  max={20}
  centerValue="8,4%"
  bands={[
    { until: 5, tone: 'success', label: 'Em dia' },
    { until: 12, tone: 'warning', label: 'Atenção' },
    { until: 20, tone: 'danger', label: 'Crítico' },
  ]}
/>
```

Cada faixa vai de onde a anterior parou até o seu `until`, e o limite é
inclusivo: em `5`, ainda está em dia. O anel fino de fora desenha as faixas, o
arco grosso de dentro vai de zero até o valor na cor da faixa em que ele caiu, e
um ponteiro marca o lugar exato sobre o anel. Sem `bands`, o medidor é um arco
neutro de acento, sem ponteiro.

## Fora da escala

O número escrito é sempre o real. Com `value={140}` e `max={100}`, o meio diz
"140" e o leitor de tela ouve "140 de 100, Crítico": só o arco, o ponteiro e a
faixa param na ponta, porque o desenho não tem para onde ir, mas a pessoa
precisa saber o quanto passou. Abaixo de zero vale o mesmo, na outra ponta. Um
`NaN` ou um infinito não é número nenhum: o meio mostra "—", sem faixa, sem
ponteiro e sem arco pintado.

Com `centerValue`, o nome acessível diz o mesmo texto que está na tela ("R$
1.234.567,89 de 2.000.000"), e não o número cru. O texto do meio tem a largura
do furo do arco, e a fonte encolhe até caber: um valor comprido fica menor, e
nunca cobre o arco nem sai do cartão.

O `sweep` vai de 0 a 360, e 360 fecha o anel.

## A cor nunca está sozinha

O nome da faixa sai escrito embaixo do número (troque por `centerLabel` se
quiser outra frase), e é ele que o leitor de tela ouve junto com o valor: "8,4
de 20, Atenção". A régua das faixas inteira vai na descrição, para quem quer
saber onde começa o crítico sem ver o anel.

As faixas pintam os papéis `success-text`, `warning-text` e `danger-text`, e não
`success`, `warning` e `danger`. A diferença é medida: o arco é desenhado por
cima do trilho, e o `danger` do tema escuro sobre o trilho dava 2,99:1, abaixo
dos 3:1 que a norma pede para um objeto que precisa ser percebido. A faixa
crítica, justamente, era a única que sumia.

## Contra o Meter e o ChartRadial

As três mostram uma medida só, e a escolha é pela pergunta:

- **`Meter`** é uma barra que cabe numa linha de formulário ou de tabela, e não
  julga o número: diz quanto, e quem lê decide se é muito.
- **`ChartRadial`** é o arco de uma medida que tem **meta**: quanto falta para
  chegar. Não tem faixas, e subir é sempre melhor.
- **`ChartGauge`** é o medidor que **julga**: o número cai numa faixa com nome,
  e a faixa pode dizer que subir é pior (inadimplência, uso de cota, tempo de
  resposta). É a única das três em que a mesma cor pode ser boa num cartão e
  ruim no vizinho, porque quem decide é a faixa, e não a direção.

## Movimento

Na primeira vez que aparece, o arco e o ponteiro saem do zero até o valor, em
`--rc-duration-slow` com a curva `--rc-ease`; quando o valor muda, andam do
velho ao novo. Com "reduzir movimento", nascem no lugar.

## Quando não usar

Sem faixa que diga bom ou ruim, é o `ChartRadial`, que ocupa o mesmo cartão e
não finge um julgamento que ninguém fez. Numa linha de formulário, é o `Meter`.
E para mostrar como o número andou no mês, nenhum dos três: é `Sparkline` ou
`LineChart`, porque o medidor só sabe o agora.

## No React Native

Traduz, em `@rivocode/ui-native/chart`, com as mesmas props: `value`, `max`, `bands`, `sweep`, `centerValue`, `centerLabel`, `label`, `format`. As faixas são as mesmas, com `tone` `success`, `warning` ou `danger`, e pintam os mesmos papéis `-text` do web: a medida do arco sobre o trilho é a mesma nos dois lados, e está no mapa de contraste do nativo.

Uma mudança de tipo, a da rosca e do arco: `centerValue` e `centerLabel` são `string`. E uma de leitura: no web a régua das faixas vai numa descrição separada, ligada por `aria-describedby`; o celular não tem esse canal, então ela entra no fim do nome acessível ("72 de 100, Atenção. Bom de 0 a 60; Atenção de 60 a 85; Crítico de 85 a 100"). O papel é `image`, pela mesma razão do `ChartRadial`.

O arco e o ponteiro andam juntos até o valor novo, pelo Reanimated, e nascem no lugar com "reduzir movimento".

As partes vestem pelo mesmo `classNames` do web: `value` e `label`, os dois textos do meio. `arc` não porta como parte: o arco é desenhado no `Svg`, e o `react-native-svg` não recebe classe.

## Importação

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

## Exemplos

### Inadimplência com faixas

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

const DELAY: ChartGaugeBand[] = [
  { until: 5, tone: 'success', label: 'Em dia' },
  { until: 12, tone: 'warning', label: 'Atenção' },
  { until: 20, tone: 'danger', label: 'Crítico' },
]

const QUOTA: ChartGaugeBand[] = [
  { until: 70, tone: 'success', label: 'Folga' },
  { until: 90, tone: 'warning', label: 'Perto do limite' },
  { until: 100, tone: 'danger', label: 'No limite' },
]

export function OverdueRate() {
  return (
    <Card className="w-full max-w-72">
      <CardHeader>
        <CardTitle>Inadimplência</CardTitle>
        <CardDescription>Faturas vencidas há mais de 30 dias.</CardDescription>
      </CardHeader>
      <CardContent>
        <ChartGauge
          value={8.4}
          max={20}
          bands={DELAY}
          centerValue="8,4%"
          label="Inadimplência em 8,4%, faixa de atenção"
        />
      </CardContent>
    </Card>
  )
}

const QUOTA: ChartGaugeBand[] = [
  { until: 70, tone: 'success', label: 'Folga' },
  { until: 90, tone: 'warning', label: 'Perto do limite' },
  { until: 100, tone: 'danger', label: 'No limite' },
]
```

### Três leituras, lado a lado

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

const QUOTA: ChartGaugeBand[] = [
  { until: 70, tone: 'success', label: 'Folga' },
  { until: 90, tone: 'warning', label: 'Perto do limite' },
  { until: 100, tone: 'danger', label: 'No limite' },
]

export function ThreeReadings() {
  return (
    <div className="grid w-full max-w-[40rem] grid-cols-3 gap-4">
      <ChartGauge value={42} bands={QUOTA} centerValue="42%" />
      <ChartGauge value={81} bands={QUOTA} centerValue="81%" />
      <ChartGauge value={97} bands={QUOTA} centerValue="97%" />
    </div>
  )
}
```

### Sem faixas

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

export function WithoutBands() {
  return (
    <div className="w-full max-w-64">
      <ChartGauge value={640} max={1000} format="integer" centerLabel="de 1.000 vagas" />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `value` | `number` | sim |  | - | De 0 a `max`. |
| `bands` | `readonly ChartGaugeBand[]` |  |  | - | As faixas, em ordem, cada uma ate o seu `until`. |
| `centerLabel` | `ReactNode` |  |  | - | A linha pequena embaixo do numero. |
| `centerValue` | `ReactNode` |  |  | - | O numero grande no meio. |
| `classNames` | `Partial<Record<"arc" \| "label" \| "value", string>>` |  |  | - | Classe por parte: `arc`, `value`, `label`. |
| `format` | `Format` |  |  | - | Como o numero e escrito, no meio e no nome acessivel. |
| `label` | `string` |  |  | - | O que o leitor de tela ouve. |
| `labels` | `Partial<ChartGaugeLabels>` |  |  | - | Os textos da peca, para trocar o idioma: `value` junta o valor escrito ao maximo no nome acessivel, e `band` descreve cada faixa na regua que o leitor de tela ouve. |
| `max` | `number` |  | `100` | - |  |
| `sweep` | `number` |  | `240` | - | Quantos graus o arco cobre, com a abertura 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)
- [ChartFunnel](/componentes/chart-funnel.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)
