Meter

O mk-meter exibe uma medição visual somente leitura dentro de uma escala conhecida — força de senha, uso de disco, capacidade utilizada, nível de volume. Ele replica a semântica do elemento nativo <meter> (role="meter", aria-valuenow/min/max/valuetext) com estilização total via tokens --db1-*, e calcula automaticamente a cor semântica (success/warning/danger) a partir de low, high e optimum, eliminando a necessidade de o consumidor calcular breakpoints manualmente. Para captura de valor pelo usuário, use mk-slider; para progresso de tarefa assíncrona, use mk-progress.

Padrão

import { MkMeter } from '@db1/makuco-ui-react';

<MkMeter value={72} label="Uso de disco" showValue></MkMeter>

<mk-meter value="72" label="Uso de disco" show-value></mk-meter>

Tamanhos

Três tamanhos disponíveis via size: sm, md (padrão) e lg. A prop controla a altura da trilha e a tipografia do label/valor.

import { MkMeter } from '@db1/makuco-ui-react';

<MkMeter value={72} size="sm" label="Small" showValue></MkMeter>
<MkMeter value={72} size="md" label="Medium" showValue></MkMeter>
<MkMeter value={72} size="lg" label="Large" showValue></MkMeter>

<mk-meter value="72" size="sm" label="Small" show-value></mk-meter>
<mk-meter value="72" size="md" label="Medium" show-value></mk-meter>
<mk-meter value="72" size="lg" label="Large" show-value></mk-meter>

Cálculo automático de cor

Com variant="auto" (padrão), a cor é calculada a partir de low, high e optimum, reproduzindo o algoritmo de três regiões do elemento <meter> nativo do HTML Living Standard:

• Sem low/high/optimum: fallback de 3 faixas fixas relativas ao percentual do valor — < 34% → danger, 34%–66% → warning, > 66% → success.
• optimum < low (quanto menor, melhor): valores ≤ low → success; entre low e high → warning; > high → danger.
• optimum > high (quanto maior, melhor): valores < low → danger; entre low e high → warning; ≥ high → success.
• low ≤ optimum ≤ high (faixa intermediária é a ideal): valores < low → warning; entre low e high → success; > high → warning — não existe região danger neste caso.

Se low > high, a configuração é inválida: o componente emite um console.warn em desenvolvimento e cai no fallback de 3 faixas fixas.

import { MkMeter } from '@db1/makuco-ui-react';

<MkMeter value={20} low={34} high={67} optimum={100} label="Abaixo de low" showValue></MkMeter>
<MkMeter value={50} low={34} high={67} optimum={100} label="Entre low e high" showValue></MkMeter>
<MkMeter value={90} low={34} high={67} optimum={100} label="Acima de high" showValue></MkMeter>

<mk-meter value="20" low="34" high="67" optimum="100" label="Abaixo de low" show-value></mk-meter>
<mk-meter value="50" low="34" high="67" optimum="100" label="Entre low e high" show-value></mk-meter>
<mk-meter value="90" low="34" high="67" optimum="100" label="Acima de high" show-value></mk-meter>

Variantes explícitas

Uma variant diferente de "auto" (success, warning, danger, info, brand) sempre sobrescreve o cálculo automático — útil quando a severidade já vem calculada no backend (ex.: status: "critical" retornado por uma API).

import { MkMeter } from '@db1/makuco-ui-react';

<MkMeter value={95} variant="danger" label="Capacidade do plano" showValue></MkMeter>

<mk-meter value="95" variant="danger" label="Capacidade do plano" show-value></mk-meter>

Slot de valor customizado

O slot value substitui o texto percentual gerado automaticamente por markup customizado (ex.: "8 de 10 GB"). O slot tem prioridade sobre showValue — se houver conteúdo projetado, ele é exibido independentemente do valor da prop.

import { MkMeter } from '@db1/makuco-ui-react';

<MkMeter value={8} min={0} max={10} label="Armazenamento">
  <span slot="value">8 de 10 GB</span>
</MkMeter>

<mk-meter value="8" min="0" max="10" label="Armazenamento">
  <span slot="value">8 de 10 GB</span>
</mk-meter>

Reagindo a mudanças de severidade

O evento mkChange é disparado quando value muda ou quando a variante de cor resolvida cruza de faixa (ex.: de warning para danger), permitindo reagir programaticamente — por exemplo, disparando um mk-toast de alerta.

import { MkMeter } from '@db1/makuco-ui-react';

<MkMeter
  value={72}
  label="Uso de disco"
  showValue
  onMkChange={(e) => {
    if (e.detail.variant === 'danger') {
      console.warn('Uso de disco crítico:', e.detail.value);
    }
  }}
></MkMeter>

<mk-meter
  value="72"
  label="Uso de disco"
  show-value
  (mkChange)="onDiskUsageChange($event)"
></mk-meter>

Props

Eventos

Slots

Acessibilidade

• O host recebe role="meter" — um papel WAI-ARIA não interativo, análogo a progressbar, mas para uma medição estática dentro de uma escala conhecida, e não para o avanço de uma tarefa assíncrona.
• aria-valuenow, aria-valuemin e aria-valuemax refletem value (clampado), min e max, sempre atualizados.
• aria-valuetext comunica o significado qualitativo da faixa (ex.: "72%, atenção"), já que role="meter" não expõe low/high/optimum nativamente a tecnologias assistivas. Quando valueLabel é fornecido, ele substitui o texto gerado (ex.: "Forte").
• aria-label reflete a prop label quando não há aria-labelledby aplicado externamente pelo consumidor.
• O componente nunca recebe foco: não há tabindex no host nem em nenhum elemento interno, e não responde a Tab, Enter, Space ou setas.
• A cor nunca é o único indicador de severidade — o valor numérico/textual está sempre disponível via aria-valuetext e, opcionalmente, também visualmente via showValue.
• Contraste ≥ 4.5:1 para o texto do label/valor e ≥ 3:1 para o preenchimento da barra contra o trilho, garantido pelos tokens semânticos em ambos os temas (claro/escuro).