@etus/ui 0.1.0

package/src/components/forms/Rating/README.md

@@ -0,0 +1,729 @@
+# Rating
+
+## Visao Geral
+
+O **Rating** e o componente de avaliacao do Design System ETUS, usado para coletar ou exibir classificacoes numericas atraves de icones visuais (estrelas por padrao). Suporta modo controlado e nao-controlado, meias-estrelas, icones customizados e navegacao por teclado.
+
+### Casos de Uso
+
+- Avaliacao de produtos e servicos
+- Feedback de usuarios
+- Classificacao de conteudo
+- Indicadores de qualidade em dashboards
+- Formularios de satisfacao do cliente
+
+### Classificacao
+
+**Categoria:** Form / Input
+**Dependencias:** `lucide-react` (Star, StarHalf), `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Tamanhos (`size`)
+
+| Tamanho | Icone | Uso |
+|---------|-------|-----|
+| `sm` | `size-4` (16px) | Espacos compactos, tabelas, listas |
+| `md` | `size-5` (20px) | Uso geral |
+| `lg` | `size-6` (24px) | Destaque, formularios principais |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Empty | `text-muted-foreground` | Icone vazio, aguardando input |
+| Half | `text-warning` | Meia-estrela preenchida (quando `allowHalf`) |
+| Full | `text-warning` | Estrela completamente preenchida |
+| Hover | `hover:scale-110 hover:text-warning` | Feedback visual ao passar mouse |
+| Disabled | `opacity-50 cursor-not-allowed` | Sem interacoes, 50% opacidade |
+| ReadOnly | `cursor-default` | Apenas exibicao, sem interacoes |
+| Focus | `focus-visible:ring-2 ring-ring` | Ring de foco para navegacao por teclado |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--warning              /* Cor das estrelas preenchidas (amarelo/dourado) */
+--muted-foreground     /* Cor das estrelas vazias */
+--muted                /* Fundo da meia-estrela vazia */
+--ring                 /* Focus ring */
+
+/* Espacamento */
+gap-0.5               /* Entre itens de rating */
+
+/* Transicoes */
+transition-colors     /* Mudanca de cor suave */
+hover:scale-110       /* Efeito de escala no hover */
+
+/* Bordas */
+rounded-sm            /* Border radius dos itens focados */
+```
+
+### data-slot
+
+```html
+<div data-slot="rating" role="radiogroup">
+  <span data-slot="rating-item" role="radio" data-filled="full">...</span>
+  <span data-slot="rating-item" role="radio" data-filled="empty">...</span>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `value` | `number` | - | Valor atual (modo controlado) |
+| `defaultValue` | `number` | `0` | Valor inicial (modo nao-controlado) |
+| `max` | `number` | `5` | Numero maximo de estrelas |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tamanho visual dos icones |
+| `allowHalf` | `boolean` | `false` | Permite selecao de meia-estrela |
+| `readOnly` | `boolean` | `false` | Modo somente leitura |
+| `disabled` | `boolean` | `false` | Desabilita todas as interacoes |
+| `emptyIcon` | `ReactNode` | `<Star />` | Icone customizado para estado vazio |
+| `filledIcon` | `ReactNode` | `<Star className="fill-current" />` | Icone customizado para estado cheio |
+| `halfIcon` | `ReactNode` | `<StarHalf />` | Icone customizado para meia-estrela |
+| `onChange` | `(value: number) => void` | - | Callback ao mudar valor |
+| `onHover` | `(value: number \| null) => void` | - | Callback ao passar mouse sobre item |
+| `name` | `string` | - | Nome do campo para submissao de formulario |
+| `className` | `string` | - | Classes CSS adicionais |
+| `aria-label` | `string` | `"Rating"` | Label acessivel para o radiogroup |
+
+> Herda todas as props de `React.ComponentProps<"div">` exceto `onChange`
+
+### Callbacks
+
+| Callback | Tipo | Descricao |
+|----------|------|-----------|
+| `onChange` | `(value: number) => void` | Disparado quando o valor muda |
+| `onHover` | `(value: number \| null) => void` | Disparado ao hover/leave de um item |
+
+### TypeScript
+
+```typescript
+import type { RatingProps, RatingSize } from "@etus/ui"
+
+// RatingProps inclui:
+interface RatingProps {
+  value?: number
+  defaultValue?: number
+  max?: number
+  size?: RatingSize
+  allowHalf?: boolean
+  readOnly?: boolean
+  disabled?: boolean
+  emptyIcon?: ReactNode
+  filledIcon?: ReactNode
+  halfIcon?: ReactNode
+  onChange?: (value: number) => void
+  onHover?: (value: number | null) => void
+  name?: string
+  // ... + todas as props de <div>
+}
+
+// Tipos derivados
+type RatingSize = "sm" | "md" | "lg"
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Shadcn | MUI | Mantine | AntD | NextUI | Chakra | PrimeReact | Radix | Ariakit | Fluent | Carbon |
+|---------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|:----------:|:-----:|:-------:|:------:|:------:|
+| **Tamanhos** | 3 | - | 3 | 4 | - | 3 | - | - | - | - | 3 | - |
+| **allowHalf** | yes | - | yes | yes | yes | - | - | yes | - | - | - | - |
+| **readOnly** | yes | - | yes | yes | yes | yes | - | yes | - | - | yes | - |
+| **disabled** | yes | - | yes | yes | yes | yes | yes | yes | - | - | yes | - |
+| **Custom icons** | yes | - | yes | yes | yes | - | yes | yes | - | - | - | - |
+| **Controlled** | yes | - | yes | yes | yes | yes | yes | yes | - | - | yes | - |
+| **Uncontrolled** | yes | - | yes | yes | - | yes | yes | yes | - | - | yes | - |
+| **Hover preview** | yes | - | yes | yes | yes | - | - | - | - | - | yes | - |
+| **Keyboard nav** | yes | - | yes | yes | yes | - | - | - | - | - | yes | - |
+| **Form support** | yes | - | yes | yes | yes | - | - | yes | - | - | yes | - |
+| **Clear on reclick** | yes | - | - | - | yes | - | - | - | - | - | - | - |
+| **Tooltip** | - | - | yes | - | yes | - | - | yes | - | - | - | - |
+| **Character count** | - | - | - | - | yes | - | - | - | - | - | - | - |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | MUI | Mantine | AntD | PrimeReact | Fluent |
+|------|:----:|:---:|:-------:|:----:|:----------:|:------:|
+| `value` | yes | yes | yes | yes | yes | yes |
+| `defaultValue` | yes | yes | yes | yes | - | yes |
+| `max`/`count` | yes | yes | yes | `count` | `stars` | `max` |
+| `size` | yes | yes | yes | - | - | yes |
+| `allowHalf` | yes | `precision={0.5}` | yes | yes | yes | - |
+| `readOnly` | yes | yes | yes | - | yes | - |
+| `disabled` | yes | yes | yes | yes | yes | yes |
+| `onChange` | yes | yes | yes | yes | yes | yes |
+| `onHover` | yes | `onChangeActive` | `onHover` | `onHoverChange` | - | - |
+| `icon`/`emptyIcon` | yes | `icon` | `emptySymbol` | `character` | `offIcon` | - |
+| `name` | yes | yes | yes | - | - | - |
+
+#### Analise por Design System
+
+**MUI (Material UI):**
+- API mais completa com `precision`, `getLabelText`, `highlightSelectedOnly`
+- Suporte a feedback por cor (`emptyLabelText`)
+- Integrado com sistema de temas
+
+**Mantine:**
+- Props `emptySymbol`/`fullSymbol` para customizacao
+- `fractions` para controle granular (1/2, 1/4, etc.)
+- Suporte a `highlightSelectedOnly`
+
+**Ant Design:**
+- `character` para icone customizado (ReactNode ou funcao)
+- `tooltips` para dicas por estrela
+- `allowClear` para resetar clicando novamente
+
+**PrimeReact:**
+- API simples com `stars`, `cancel`, `onIcon`, `offIcon`
+- Menos features mas bem focado
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `role="radiogroup"` | Container do rating |
+| `role="radio"` | Cada item de rating |
+| `aria-checked` | Indica se o item esta selecionado |
+| `aria-label` | Label do radiogroup (default: "Rating") |
+| `aria-disabled` | Quando `disabled={true}` |
+| `aria-readonly` | Quando `readOnly={true}` |
+
+### Suporte a Teclado
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Move foco para/do rating |
+| `ArrowRight` / `ArrowUp` | Incrementa valor |
+| `ArrowLeft` / `ArrowDown` | Decrementa valor |
+| `Home` | Define valor como 0 |
+| `End` | Define valor como maximo |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegacao por teclado
+focus-visible:outline-none
+focus-visible:ring-2
+focus-visible:ring-ring
+focus-visible:ring-offset-1
+rounded-sm
+```
+
+### Contraste de Cores
+
+| Estado | Foreground | Background | Ratio |
+|--------|------------|------------|-------|
+| Empty | `--muted-foreground` | - | >= 4.5:1 |
+| Filled | `--warning` | - | >= 4.5:1 |
+
+### Screen Readers
+
+- Cada estrela anuncia "X star(s)" para o leitor de tela
+- O radiogroup tem label acessivel configuravel
+- Estados disabled/readonly sao anunciados
+
+### Comparativo A11y (Design Systems)
+
+| Feature | ETUS | MUI | Mantine | AntD | Fluent | React Aria |
+|---------|:----:|:---:|:-------:|:----:|:------:|:----------:|
+| **role="radiogroup"** | yes | yes | - | - | yes | yes |
+| **Keyboard nav** | yes | yes | yes | yes | yes | yes |
+| **Focus visible** | yes | yes | yes | yes | yes | yes |
+| **aria-label** | yes | yes | - | - | yes | yes |
+| **Screen reader tested** | - | yes | ~ | ~ | yes | yes |
+| **RTL support** | - | yes | yes | yes | yes | yes |
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Rating } from "@etus/ui"
+
+function Example() {
+  return <Rating defaultValue={3} />
+}
+```
+
+### Modo Controlado
+
+```tsx
+import { useState } from "react"
+import { Rating } from "@etus/ui"
+
+function ControlledRating() {
+  const [value, setValue] = useState(2.5)
+
+  return (
+    <div>
+      <Rating value={value} onChange={setValue} allowHalf />
+      <p>Valor selecionado: {value}</p>
+    </div>
+  )
+}
+```
+
+### Tamanhos
+
+```tsx
+<Rating size="sm" defaultValue={3} />
+<Rating size="md" defaultValue={3} />
+<Rating size="lg" defaultValue={3} />
+```
+
+### Meia-Estrela
+
+```tsx
+<Rating allowHalf defaultValue={2.5} />
+```
+
+### Numero Customizado de Estrelas
+
+```tsx
+<Rating max={10} defaultValue={7} />
+```
+
+### Somente Leitura
+
+```tsx
+// Exibe avaliacao sem permitir alteracao
+<Rating value={4.5} allowHalf readOnly />
+```
+
+### Desabilitado
+
+```tsx
+<Rating value={3} disabled />
+```
+
+### Icones Customizados
+
+```tsx
+import { Heart, HeartCrack } from "lucide-react"
+
+function HeartRating() {
+  return (
+    <Rating
+      defaultValue={3}
+      emptyIcon={<HeartCrack className="text-muted-foreground" />}
+      filledIcon={<Heart className="fill-red-500 text-red-500" />}
+    />
+  )
+}
+```
+
+### Com Hover Preview
+
+```tsx
+import { useState } from "react"
+import { Rating } from "@etus/ui"
+
+function RatingWithPreview() {
+  const [hoverValue, setHoverValue] = useState<number | null>(null)
+  const [value, setValue] = useState(0)
+
+  const displayValue = hoverValue ?? value
+
+  return (
+    <div>
+      <Rating
+        value={value}
+        onChange={setValue}
+        onHover={setHoverValue}
+      />
+      <p>
+        {hoverValue !== null
+          ? `Voce selecionaria ${hoverValue} estrelas`
+          : value > 0
+            ? `Voce selecionou ${value} estrelas`
+            : "Selecione uma avaliacao"
+        }
+      </p>
+    </div>
+  )
+}
+```
+
+### Em Formulario
+
+```tsx
+import { Rating } from "@etus/ui"
+
+function ProductReviewForm() {
+  return (
+    <form action="/api/review" method="POST">
+      <label htmlFor="rating">Sua avaliacao:</label>
+      <Rating
+        name="rating"
+        defaultValue={0}
+        aria-label="Avaliacao do produto"
+      />
+      <button type="submit">Enviar</button>
+    </form>
+  )
+}
+```
+
+### Com React Hook Form
+
+```tsx
+import { useController, useForm } from "react-hook-form"
+import { Rating } from "@etus/ui"
+
+function ReviewForm() {
+  const { control, handleSubmit } = useForm({
+    defaultValues: { rating: 0 }
+  })
+
+  const { field } = useController({
+    name: "rating",
+    control,
+    rules: { min: { value: 1, message: "Selecione uma avaliacao" } }
+  })
+
+  return (
+    <form onSubmit={handleSubmit(console.log)}>
+      <Rating
+        value={field.value}
+        onChange={field.onChange}
+        aria-label="Avaliacao"
+      />
+      <button type="submit">Enviar</button>
+    </form>
+  )
+}
+```
+
+### Exibindo Media de Avaliacoes
+
+```tsx
+function ProductRating({ average, count }: { average: number; count: number }) {
+  return (
+    <div className="flex items-center gap-2">
+      <Rating value={average} allowHalf readOnly size="sm" />
+      <span className="text-sm text-muted-foreground">
+        {average.toFixed(1)} ({count} avaliacoes)
+      </span>
+    </div>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Rating.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { Rating } from "./Rating"
+
+describe("Rating", () => {
+  it("renders correct number of stars", () => {
+    render(<Rating max={5} />)
+    const stars = screen.getAllByRole("radio")
+    expect(stars).toHaveLength(5)
+  })
+
+  it("applies default value correctly", () => {
+    render(<Rating defaultValue={3} />)
+    const stars = screen.getAllByRole("radio")
+    expect(stars[0]).toHaveAttribute("data-filled", "full")
+    expect(stars[1]).toHaveAttribute("data-filled", "full")
+    expect(stars[2]).toHaveAttribute("data-filled", "full")
+    expect(stars[3]).toHaveAttribute("data-filled", "empty")
+  })
+
+  it("applies size classes", () => {
+    render(<Rating size="lg" />)
+    expect(screen.getByRole("radiogroup")).toHaveClass("[&_svg]:size-6")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Rating />)
+    expect(screen.getByRole("radiogroup")).toHaveAttribute("data-slot", "rating")
+  })
+})
+```
+
+### Testes de Interacao
+
+```tsx
+describe("Rating interactions", () => {
+  it("calls onChange when clicking a star", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<Rating onChange={handleChange} />)
+    await user.click(screen.getAllByRole("radio")[2])
+
+    expect(handleChange).toHaveBeenCalledWith(3)
+  })
+
+  it("supports keyboard navigation", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<Rating defaultValue={2} onChange={handleChange} />)
+
+    const rating = screen.getByRole("radiogroup")
+    rating.focus()
+    await user.keyboard("{ArrowRight}")
+
+    expect(handleChange).toHaveBeenCalledWith(3)
+  })
+
+  it("does not call onChange when disabled", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<Rating onChange={handleChange} disabled />)
+    await user.click(screen.getAllByRole("radio")[2])
+
+    expect(handleChange).not.toHaveBeenCalled()
+  })
+
+  it("does not call onChange when readOnly", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<Rating onChange={handleChange} readOnly value={3} />)
+    await user.click(screen.getAllByRole("radio")[4])
+
+    expect(handleChange).not.toHaveBeenCalled()
+  })
+
+  it("calls onHover on mouse enter/leave", async () => {
+    const user = userEvent.setup()
+    const handleHover = vi.fn()
+
+    render(<Rating onHover={handleHover} />)
+
+    await user.hover(screen.getAllByRole("radio")[3])
+    expect(handleHover).toHaveBeenCalledWith(4)
+
+    await user.unhover(screen.getAllByRole("radio")[3])
+    expect(handleHover).toHaveBeenCalledWith(null)
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Rating accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Rating aria-label="Product rating" />)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has correct ARIA attributes", () => {
+    render(<Rating aria-label="Rate this product" />)
+
+    const radiogroup = screen.getByRole("radiogroup")
+    expect(radiogroup).toHaveAttribute("aria-label", "Rate this product")
+
+    const radios = screen.getAllByRole("radio")
+    expect(radios[0]).toHaveAttribute("aria-label", "1 star")
+    expect(radios[1]).toHaveAttribute("aria-label", "2 stars")
+  })
+
+  it("marks disabled state correctly", () => {
+    render(<Rating disabled />)
+    expect(screen.getByRole("radiogroup")).toHaveAttribute("aria-disabled", "true")
+  })
+
+  it("marks readonly state correctly", () => {
+    render(<Rating readOnly value={3} />)
+    expect(screen.getByRole("radiogroup")).toHaveAttribute("aria-readonly", "true")
+  })
+})
+```
+
+### Testes de Formulario
+
+```tsx
+describe("Rating form integration", () => {
+  it("includes hidden input with name and value", () => {
+    render(<Rating name="product-rating" defaultValue={4} />)
+
+    const hiddenInput = document.querySelector('input[name="product-rating"]')
+    expect(hiddenInput).toBeInTheDocument()
+    expect(hiddenInput).toHaveValue("4")
+  })
+
+  it("updates hidden input on value change", async () => {
+    const user = userEvent.setup()
+    render(<Rating name="rating" defaultValue={2} />)
+
+    await user.click(screen.getAllByRole("radio")[4])
+
+    const hiddenInput = document.querySelector('input[name="rating"]')
+    expect(hiddenInput).toHaveValue("5")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com design systems de referencia:
+
+### Prioridade Alta
+
+#### `precision`
+
+Controle granular de fracao (1/4, 1/3, 1/2).
+
+```tsx
+// Proposta de API
+interface RatingProps {
+  precision?: 0.25 | 0.5 | 1
+}
+
+// Uso
+<Rating precision={0.25} /> // Permite 0.25, 0.5, 0.75, 1, etc.
+```
+
+**Referencias:** MUI (`precision`), Mantine (`fractions`)
+
+#### `highlightSelectedOnly`
+
+Destaca apenas a estrela selecionada, nao todas anteriores.
+
+```tsx
+// Proposta de API
+<Rating highlightSelectedOnly />
+```
+
+**Referencias:** MUI, Mantine
+
+### Prioridade Media
+
+#### `tooltips`
+
+Dicas por estrela.
+
+```tsx
+// Proposta de API
+interface RatingProps {
+  tooltips?: string[]
+}
+
+// Uso
+<Rating tooltips={["Pessimo", "Ruim", "Regular", "Bom", "Excelente"]} />
+```
+
+**Referencias:** AntD (`tooltips`), PrimeReact
+
+#### `getLabelText`
+
+Funcao para customizar texto acessivel.
+
+```tsx
+// Proposta de API
+interface RatingProps {
+  getLabelText?: (value: number) => string
+}
+
+// Uso
+<Rating getLabelText={(v) => `${v} de 5 estrelas`} />
+```
+
+**Referencias:** MUI
+
+### Prioridade Baixa
+
+#### `color`
+
+Cor customizada das estrelas.
+
+```tsx
+// Proposta de API
+interface RatingProps {
+  color?: "warning" | "primary" | "destructive" | string
+}
+
+// Uso
+<Rating color="primary" />
+```
+
+**Referencias:** Mantine, NextUI
+
+#### `clearable` / `allowClear`
+
+Prop explicita para permitir limpar clicando na mesma estrela.
+
+```tsx
+// Atualmente ja funciona por padrao
+// Poderia ter prop para desabilitar
+<Rating clearable={false} />
+```
+
+**Referencias:** AntD (`allowClear`)
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| `precision` | Avaliar | `allowHalf` cobre maioria dos casos |
+| `highlightSelectedOnly` | Implementar | Util para casos especificos |
+| `tooltips` | Implementar | Melhora UX significativamente |
+| `getLabelText` | Implementar | Melhora a11y |
+| `color` | Evitar | Usar className ou CSS variables |
+| `clearable` | Evitar | Comportamento atual ja permite |
+
+---
+
+## Referencias
+
+### Design Systems Analisados
+
+| Design System | Documentacao Rating | GitHub |
+|---------------|---------------------|--------|
+| **MUI** | [Rating](https://mui.com/material-ui/react-rating/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [Rating](https://mantine.dev/core/rating/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Rate](https://ant.design/components/rate) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **PrimeReact** | [Rating](https://primereact.org/rating/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+| **NextUI** | - | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Chakra UI** | - | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **Fluent UI** | [Rating](https://react.fluentui.dev/?path=/docs/components-rating--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **React Aria** | - | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - Radio Group Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - ARIA: radiogroup role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Lucide Icons](https://lucide.dev/icons/)