Rating

Avaliação por estrelas interativa. Suporta valores inteiros e meios valores, múltiplos tamanhos, modo somente leitura e navegação por teclado com semântica de radiogroup. O mk-rating-tag exibe o score e a contagem de avaliações em formato de chip.

Quando usar

Use o mk-rating quando:

• Precisar exibir a avaliação média de um item (produto, prestador, conteúdo, serviço).
• O contexto exigir que o usuário entenda rapidamente a qualidade percebida.
• A pontuação for complementada pelo número de avaliações para dar credibilidade.

Prefira uma alternativa quando:

• O usuário precisar dar uma avaliação — use mk-rating em modo interativo (sem readonly).
• Quiser exibir apenas badge numérico sem as estrelas — use mk-rating-tag.
• O espaço for muito reduzido — considere mk-rating-tag.

Anatomia

Variantes

• Tamanho sm: contextos compactos — listas de produtos, cards de item, tabelas. Estrelas pequenas, pontuação 14px, contagem 12px.
• Tamanho md: uso geral — cards de destaque, páginas de listagem. Pontuação 20px, contagem 14px.
• Tamanho lg: contextos de destaque — topo de página de detalhe, seção de avaliações, hero de produto. Estrelas médias, pontuação 24px, contagem 16px.

Comportamento

O mk-rating em modo readonly é somente leitura — exibe avaliação já computada, não captura nota do usuário. O valor das estrelas é representado com até meia estrela de precisão (nota 4,5 exibe 4 estrelas preenchidas e 1 semi-preenchida).

Pontuação e contagem são configuráveis de forma independente. Pode exibir:

• Apenas estrelas.
• Estrelas + pontuação.
• Estrelas + contagem.
• Estrelas + pontuação + contagem (padrão completo).

Estados da estrela

Composição

O mk-rating aparece frequentemente dentro de cards de produto, listas de resultados e páginas de detalhe. Em contextos muito compactos (linha de tabela, chip), prefira mk-rating-tag que condensa a informação em um badge. Quando o objetivo é coletar a nota do usuário, use as estrelas (mk-rating) em modo interativo diretamente, sem readonly.

Padrão

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

<MkRating value={3} />

<mk-rating value="3"></mk-rating>

Meia estrela

Ative allowHalf para permitir seleções de meio valor (ex: 2.5). As zonas de clique são divididas horizontalmente: metade esquerda seleciona o meio valor, metade direita seleciona o valor inteiro.

<MkRating value={2.5} allowHalf={true} />

<mk-rating value="2.5" allow-half="true"></mk-rating>

Somente leitura

Use readonly para exibir uma avaliação sem permitir interação do usuário.

<MkRating value={4} readonly={true} />

<mk-rating value="4" readonly="true"></mk-rating>

Desabilitado

Use disabled para bloquear completamente a interação.

<MkRating value={3} disabled={true} />

<mk-rating value="3" disabled="true"></mk-rating>

Tamanhos

O componente suporta três tamanhos: sm, md e lg. O tamanho lg é projetado para uso com showScore e showCount, pois aplica uma escala tipográfica maior.

<MkRating value={3} size="sm" />
<MkRating value={3} size="md" />
<MkRating value={3} size="lg" showScore={true} showCount={true} count="128 avaliações" readonly={true} />

<mk-rating value="3" size="sm"></mk-rating>
<mk-rating value="3" size="md"></mk-rating>
<mk-rating value="3" size="lg" show-score show-count count="128 avaliações" readonly></mk-rating>

Score e contagem

Use showScore para exibir o valor numérico formatado ao lado das estrelas. Use showCount junto com a prop count para exibir a contagem de avaliações. Ideal para modo readonly com dados vindos de uma API.

<MkRating
  value={4.5}
  allowHalf={true}
  readonly={true}
  size="sm"
  showScore={true}
  showCount={true}
  count="128 avaliações"
/>

<mk-rating
  value="4.5"
  allow-half
  readonly
  size="sm"
  show-score
  show-count
  count="128 avaliações"
></mk-rating>

Rating Tag

O mk-rating-tag exibe o score e a contagem de avaliações em formato de chip compacto com uma única estrela. Disponível em três tamanhos.

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

<MkRatingTag value={4.5} count="128" size="sm" />
<MkRatingTag value={4.5} count="128" size="md" />
<MkRatingTag value={4.5} count="128" size="lg" />

<mk-rating-tag value="4.5" count="128" size="sm"></mk-rating-tag>
<mk-rating-tag value="4.5" count="128" size="md"></mk-rating-tag>
<mk-rating-tag value="4.5" count="128" size="lg"></mk-rating-tag>

Props — mk-rating

Props — mk-rating-tag

Eventos

Acessibilidade

• O Host usa role="radiogroup" e cada estrela usa role="radio" com aria-checked
• Navegação por teclado: ArrowRight aumenta o valor, ArrowLeft diminui; com allowHalf, o incremento é de 0.5
• aria-disabled="true" é definido automaticamente quando disabled=true
• aria-readonly="true" é definido automaticamente quando readonly=true
• Roving tabindex: apenas a estrela do valor atual recebe tabIndex=0
• Em modo readonly, o componente é uma representação visual — certifique-se de incluir um texto alternativo acessível no contexto de uso (ex.: via aria-label no container pai) para que leitores de tela transmitam a nota ao usuário sem depender apenas das estrelas visuais