# Rating

> Una calificación con estrellas: de solo lectura, con fracciones, o como campo de un formulario.

```tsx
import { Rating } from "sebs7n-ui/rating"
```

## Ejemplos

### Solo lectura

El promedio de las reseñas de un proveedor, con fracciones. Se lee como «4,5 de 5 estrellas».

```tsx
import { Rating } from "sebs7n-ui/rating"

function ReadOnly() {
  return (
    <div className="flex flex-col gap-3">
      <div className="flex items-center gap-2">
        <Rating readOnly value={4.5} />
        <span className="text-callout text-label-secondary">4,5 · 128 reseñas</span>
      </div>
      <Rating readOnly size="sm" value={3} />
    </div>
  )
}
```

### En un formulario

Un `radiogroup`: flechas, Inicio y Fin. Con `required`, sin valor no se envía.

```tsx
import { Field, FieldDescription, FieldError, FieldLabel } from "sebs7n-ui/field"
import { Rating } from "sebs7n-ui/rating"

function InForm() {
  return (
    <div className="w-full max-w-sm">
      <Field name="score">
        <FieldLabel>¿Cómo fue la atención?</FieldLabel>
        <Rating required size="lg" />
        <FieldDescription>Del 1 al 5.</FieldDescription>
        <FieldError />
      </Field>
    </div>
  )
}
```

## Props

### Rating

Hereda las props de `<div>`.

| Prop | Tipo | Por defecto | Descripción |
|---|---|---|---|
| `aria-describedby` | `string` | — | El `id` de una ayuda. |
| `aria-label` | `string` | — | Nombra el grupo; de solo lectura, reemplaza «4,5 de 5 estrellas». |
| `aria-labelledby` | `string` | — | El `id` del elemento que nombra el grupo. |
| `defaultValue` | `number` | `null` | El valor al montar, sin controlar. |
| `disabled` | `boolean` | — | Apaga la interacción y lo marca con `data-disabled`, que es el atributo del que cuelgan los estilos de apagado. |
| `id` | `string` | — | El `id` del grupo. |
| `labels` | `Partial<RatingLabels>` | — | Textos: `star`, `stars`, `of` y `locale` (el de los decimales). Por defecto, `ratingLabels`. |
| `max` | `number` | `5` | Cuántas estrellas. Por defecto, 5. |
| `name` | `string` | — | El nombre con el que viaja en un formulario («4»; vacío sin valor). |
| `onValueChange` | `(value: number) => void` | — | Avisa el valor elegido. |
| `readOnly` | `boolean` | `false` | Solo muestra el valor (el de una reseña): una imagen con el valor en palabras, sin foco. Es un dato mostrado, no una respuesta: no se registra en `Form` ni viaja en el form nativo, aunque tenga `name`. |
| `required` | `boolean` | `false` | Sin valor no se puede enviar: dentro de un `Form`, el campo queda inválido y `Form` lo enfoca. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Estrellas de 16, 20 (default) o 24. El área de toque es de 24 como mínimo. |
| `value` | `number` | — | El valor, controlado: de 1 a `max`, o `null` sin elegir. De solo lectura admite fracciones (4,5). |
| `className` | `string` | — | Se fusiona con las clases del componente vía `cn()` (tailwind-merge): lo que pongas gana. |

## Teclado

| Tecla | Qué hace |
|---|---|
| Tab | Entra en la estrella elegida (o en la primera) y sale del grupo. |
| ← → ↑ ↓ | Bajan o suben una estrella y la eligen. |
| Inicio · Fin | Eligen la primera o la última. |
| Espacio · Enter | Eligen la estrella enfocada. |

## Accesibilidad

- Como campo es un `radiogroup` (el patrón de ARIA): una estrella radio por valor, nombrada «4 estrellas», con un solo `tabindex=0`. Nombralo con `aria-label` o con un `FieldLabel`.
- De solo lectura es una imagen con el valor en palabras («4,5 de 5 estrellas»); las estrellas son decorativas.
- La estrella llena (`amber-900`) y la vacía (`label-tertiary`) llegan a 3:1 sobre la página y la card en los dos temas. Cada estrella tiene 24 de área de toque aunque mida 16.

## Reglas de uso

- `readOnly` para mostrar el promedio de una reseña, con fracciones (la estrella se llena en parte). Es un dato mostrado: no se registra en `Form` ni viaja en el form, aunque tenga `name`. Como entrada, solo valores enteros: media estrella es más precisión de la que alguien sabe dar.
- Con `name` viaja en el form («4», vacío sin valor). Dentro de un `Field`, `Form` manda el número y, con `required`, no deja enviar sin valor y enfoca la estrella.
- `size`: estrellas de 16, 20 (default) o 24; `max` cambia la escala.
- Solo por subpath (`sebs7n-ui/rating`).

## Relacionados

[radio-group](/docs/components/radio-group.md) · [field](/docs/components/field.md)