@etus/ui 0.1.0

package/src/components/data-display/Sparkline/README.md

@@ -0,0 +1,321 @@
+# Sparkline
+
+## Visão Geral
+
+O Sparkline e um grafico minimalista inline projetado para ser exibido junto com texto ou em espacos compactos. Mostra tendencias de forma simplificada sem eixos, labels ou legendas, focando apenas na forma da curva.
+
+### Classificacao Atomica
+- **Categoria**: Atoms
+- **Subcategoria**: Data Display / Charts
+
+### Casos de Uso Comuns
+- Tendencia ao lado de metricas em tabelas
+- Mini graficos em KPI cards
+- Indicadores de performance inline
+- Historico de precos de acoes
+- Graficos em celulas de tabela
+- Widgets de dashboard compactos
+
+### Relacao com Outros Componentes
+- **LineChart**: Versao completa com eixos
+- **AreaChart**: Versao com preenchimento
+- **KPICard**: Container comum
+- **SingleStat**: Combina valor com sparkline
+- **Table**: Sparklines em celulas
+
+## Design Specs
+
+### Variantes
+
+| Variante | Descricao |
+|----------|-----------|
+| `line` | Linha simples (padrao) |
+| `area` | Com preenchimento abaixo |
+| `bar` | Barras verticais |
+
+### Tamanhos
+
+| Tamanho | Dimensoes | Uso |
+|---------|-----------|-----|
+| `xs` | 40x16 | Em texto inline |
+| `sm` | 60x20 | Em celulas de tabela |
+| `md` | 80x24 | Em cards |
+| `lg` | 120x32 | Destaque |
+
+### Estados
+
+- **Default**: Curva renderizada
+- **Positive**: Cor verde (ultimo > primeiro)
+- **Negative**: Cor vermelha (ultimo < primeiro)
+- **Neutral**: Cor neutra
+
+### Tokens de Design
+
+#### Cores
+- Line/Area Positive: `text-success` ou `hsl(var(--chart-1))`
+- Line/Area Negative: `text-destructive` ou `hsl(var(--chart-2))`
+- Line/Area Neutral: `text-muted-foreground`
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `data` | `number[]` | - | Array de valores (obrigatorio) |
+| `variant` | `"line" \| "area" \| "bar"` | `"line"` | Tipo de grafico |
+| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"sm"` | Tamanho |
+| `width` | `number` | auto | Largura em pixels |
+| `height` | `number` | auto | Altura em pixels |
+| `color` | `string` | auto | Cor fixa |
+| `showTrend` | `boolean` | `false` | Colorir baseado em tendencia |
+| `showDots` | `boolean` | `false` | Mostrar pontos |
+| `showEndDot` | `boolean` | `false` | Mostrar apenas ponto final |
+| `strokeWidth` | `number` | `1.5` | Espessura da linha |
+| `className` | `string` | `""` | Classes adicionais |
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { Sparkline } from '@etus/ui'
+
+function BasicSparkline() {
+  const data = [4, 8, 15, 16, 23, 42, 38, 45, 52, 48]
+
+  return <Sparkline data={data} />
+}
+```
+
+### Com Indicador de Tendencia
+
+```tsx
+function TrendSparkline() {
+  const positiveData = [10, 15, 12, 18, 25, 30, 28, 35]
+  const negativeData = [35, 30, 28, 25, 20, 18, 15, 12]
+
+  return (
+    <div className="space-y-2">
+      <Sparkline data={positiveData} showTrend />
+      <Sparkline data={negativeData} showTrend />
+    </div>
+  )
+}
+```
+
+### Area Sparkline
+
+```tsx
+function AreaSparkline() {
+  return (
+    <Sparkline
+      data={[4, 8, 15, 16, 23, 42]}
+      variant="area"
+      size="md"
+    />
+  )
+}
+```
+
+### Bar Sparkline
+
+```tsx
+function BarSparkline() {
+  return (
+    <Sparkline
+      data={[4, 8, 15, 16, 23, 42, 38]}
+      variant="bar"
+      size="md"
+    />
+  )
+}
+```
+
+### Em Tabela
+
+```tsx
+import { Table, TableHeader, TableRow, TableHead, TableBody, TableCell } from '@etus/ui'
+
+function TableWithSparklines() {
+  const stocks = [
+    { symbol: 'AAPL', price: 178.52, data: [170, 172, 175, 173, 178, 176, 178.52] },
+    { symbol: 'GOOGL', price: 141.80, data: [145, 143, 140, 142, 139, 141, 141.80] },
+  ]
+
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Symbol</TableHead>
+          <TableHead>Trend</TableHead>
+          <TableHead className="text-right">Price</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {stocks.map((stock) => (
+          <TableRow key={stock.symbol}>
+            <TableCell>{stock.symbol}</TableCell>
+            <TableCell>
+              <Sparkline data={stock.data} size="sm" showTrend />
+            </TableCell>
+            <TableCell className="text-right">${stock.price}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  )
+}
+```
+
+### Em SingleStat
+
+```tsx
+import { Card, CardContent } from '@etus/ui'
+
+function StatWithSparkline() {
+  return (
+    <Card>
+      <CardContent className="p-4">
+        <div className="flex items-center justify-between">
+          <div>
+            <p className="text-sm text-muted-foreground">Revenue</p>
+            <p className="text-2xl font-bold">$45,231.89</p>
+          </div>
+          <Sparkline
+            data={[20, 25, 30, 28, 35, 40, 38, 42, 45]}
+            size="md"
+            showTrend
+            showEndDot
+          />
+        </div>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+### Inline com Texto
+
+```tsx
+function InlineSparkline() {
+  return (
+    <p className="flex items-center gap-2">
+      Revenue is up
+      <Sparkline
+        data={[10, 12, 15, 18, 22, 25]}
+        size="xs"
+        color="hsl(var(--success))"
+      />
+      this quarter.
+    </p>
+  )
+}
+```
+
+### Implementacao SVG
+
+```tsx
+function SparklineImplementation({
+  data,
+  width = 80,
+  height = 24,
+  strokeWidth = 1.5,
+}: {
+  data: number[]
+  width?: number
+  height?: number
+  strokeWidth?: number
+}) {
+  if (data.length === 0) return null
+
+  const min = Math.min(...data)
+  const max = Math.max(...data)
+  const range = max - min || 1
+
+  const points = data.map((value, index) => {
+    const x = (index / (data.length - 1)) * width
+    const y = height - ((value - min) / range) * height
+    return `${x},${y}`
+  }).join(' ')
+
+  const trend = data[data.length - 1] >= data[0] ? 'positive' : 'negative'
+  const color = trend === 'positive'
+    ? 'hsl(var(--success))'
+    : 'hsl(var(--destructive))'
+
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      className="overflow-visible"
+    >
+      <polyline
+        points={points}
+        fill="none"
+        stroke={color}
+        strokeWidth={strokeWidth}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+```
+
+## Acessibilidade (A11y)
+
+### Recomendacoes
+- Sempre acompanhar de valor numerico
+- Fornecer texto alternativo descritivo
+- Nao depender apenas do sparkline para informacao
+
+### ARIA
+- `role="img"` no SVG
+- `aria-label` descritivo
+
+```tsx
+<svg
+  role="img"
+  aria-label={`Trend chart showing ${trend} movement from ${data[0]} to ${data[data.length - 1]}`}
+>
+  {/* ... */}
+</svg>
+```
+
+## Testes
+
+```typescript
+import { render, screen } from '@testing-library/react'
+import { Sparkline } from './Sparkline'
+
+describe('Sparkline', () => {
+  it('renders with data', () => {
+    render(<Sparkline data={[1, 2, 3, 4, 5]} />)
+
+    expect(screen.getByRole('img')).toBeInTheDocument()
+  })
+
+  it('applies trend color correctly', () => {
+    const { container } = render(
+      <Sparkline data={[1, 2, 3, 4, 5]} showTrend />
+    )
+
+    const line = container.querySelector('polyline')
+    expect(line).toHaveAttribute('stroke', expect.stringContaining('success'))
+  })
+
+  it('handles empty data', () => {
+    const { container } = render(<Sparkline data={[]} />)
+
+    expect(container.firstChild).toBeNull()
+  })
+})
+```
+
+## Referências
+
+- [Edward Tufte - Sparklines](https://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0001OR)
+- [D3 Sparklines](https://observablehq.com/@d3/sparkline)
+- [Tremor SparkChart](https://www.tremor.so/docs/visualizations/spark-chart)

package/src/components/data-display/Sparkline/Sparkline.test.tsx

@@ -0,0 +1,276 @@
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+
+import { Sparkline } from "./Sparkline"
+
+describe("Sparkline", () => {
+  describe("Basic Rendering", () => {
+    it("renders with data", () => {
+      render(<Sparkline data={[1, 2, 3, 4, 5]} />)
+
+      expect(screen.getByRole("img")).toBeInTheDocument()
+    })
+
+    it("renders null when data is empty", () => {
+      const { container } = render(<Sparkline data={[]} />)
+
+      expect(container.firstChild).toBeNull()
+    })
+
+    it("applies correct data-slot attribute", () => {
+      render(<Sparkline data={[1, 2, 3]} />)
+
+      expect(screen.getByRole("img")).toHaveAttribute("data-slot", "sparkline")
+    })
+
+    it("applies custom className", () => {
+      render(<Sparkline className="custom-class" data={[1, 2, 3]} />)
+
+      expect(screen.getByRole("img")).toHaveClass("custom-class")
+    })
+  })
+
+  describe("Accessibility", () => {
+    it("has role='img' on the svg element", () => {
+      render(<Sparkline data={[1, 2, 3, 4, 5]} />)
+
+      expect(screen.getByRole("img")).toBeInTheDocument()
+    })
+
+    it("generates aria-label with trend information", () => {
+      render(<Sparkline data={[1, 2, 3, 4, 5]} />)
+
+      const svg = screen.getByRole("img")
+      expect(svg).toHaveAttribute(
+        "aria-label",
+        expect.stringContaining("upward")
+      )
+      expect(svg).toHaveAttribute(
+        "aria-label",
+        expect.stringContaining("from 1 to 5")
+      )
+    })
+
+    it("generates aria-label for downward trend", () => {
+      render(<Sparkline data={[5, 4, 3, 2, 1]} />)
+
+      const svg = screen.getByRole("img")
+      expect(svg).toHaveAttribute(
+        "aria-label",
+        expect.stringContaining("downward")
+      )
+    })
+
+    it("generates aria-label for stable trend", () => {
+      render(<Sparkline data={[3, 3, 3, 3, 3]} />)
+
+      const svg = screen.getByRole("img")
+      expect(svg).toHaveAttribute(
+        "aria-label",
+        expect.stringContaining("stable")
+      )
+    })
+  })
+
+  describe("Sizes", () => {
+    it("renders with xs size (40x16)", () => {
+      render(<Sparkline data={[1, 2, 3]} size="xs" />)
+
+      const svg = screen.getByRole("img")
+      expect(svg).toHaveAttribute("width", "40")
+      expect(svg).toHaveAttribute("height", "16")
+    })
+
+    it("renders with sm size (60x20) - default", () => {
+      render(<Sparkline data={[1, 2, 3]} />)
+
+      const svg = screen.getByRole("img")
+      expect(svg).toHaveAttribute("width", "60")
+      expect(svg).toHaveAttribute("height", "20")
+    })
+
+    it("renders with md size (80x24)", () => {
+      render(<Sparkline data={[1, 2, 3]} size="md" />)
+
+      const svg = screen.getByRole("img")
+      expect(svg).toHaveAttribute("width", "80")
+      expect(svg).toHaveAttribute("height", "24")
+    })
+
+    it("renders with lg size (120x32)", () => {
+      render(<Sparkline data={[1, 2, 3]} size="lg" />)
+
+      const svg = screen.getByRole("img")
+      expect(svg).toHaveAttribute("width", "120")
+      expect(svg).toHaveAttribute("height", "32")
+    })
+
+    it("allows custom width and height to override size", () => {
+      render(<Sparkline data={[1, 2, 3]} height={50} size="sm" width={100} />)
+
+      const svg = screen.getByRole("img")
+      expect(svg).toHaveAttribute("width", "100")
+      expect(svg).toHaveAttribute("height", "50")
+    })
+  })
+
+  describe("Variants", () => {
+    it("renders line variant by default", () => {
+      const { container } = render(<Sparkline data={[1, 2, 3, 4, 5]} />)
+
+      expect(container.querySelector("polyline")).toBeInTheDocument()
+      expect(container.querySelector("rect")).not.toBeInTheDocument()
+    })
+
+    it("renders area variant with fill", () => {
+      const { container } = render(
+        <Sparkline data={[1, 2, 3, 4, 5]} variant="area" />
+      )
+
+      expect(container.querySelector("path")).toBeInTheDocument()
+      expect(container.querySelector("polyline")).toBeInTheDocument()
+    })
+
+    it("renders bar variant with rectangles", () => {
+      const { container } = render(
+        <Sparkline data={[1, 2, 3, 4, 5]} variant="bar" />
+      )
+
+      const rects = container.querySelectorAll("rect")
+      expect(rects.length).toBe(5) // One rect per data point
+    })
+  })
+
+  describe("Trend Coloring", () => {
+    it("applies trend color when showTrend is true", () => {
+      const { container } = render(
+        <Sparkline showTrend data={[1, 2, 3, 4, 5]} />
+      )
+
+      const polyline = container.querySelector("polyline")
+      expect(polyline).toHaveAttribute(
+        "stroke",
+        expect.stringContaining("success")
+      )
+    })
+
+    it("applies negative trend color", () => {
+      const { container } = render(
+        <Sparkline showTrend data={[5, 4, 3, 2, 1]} />
+      )
+
+      const polyline = container.querySelector("polyline")
+      expect(polyline).toHaveAttribute(
+        "stroke",
+        expect.stringContaining("destructive")
+      )
+    })
+
+    it("applies neutral color for flat trend", () => {
+      const { container } = render(
+        <Sparkline showTrend data={[3, 3, 3, 3, 3]} />
+      )
+
+      const polyline = container.querySelector("polyline")
+      expect(polyline).toHaveAttribute(
+        "stroke",
+        expect.stringContaining("muted-foreground")
+      )
+    })
+
+    it("uses explicit color when provided", () => {
+      const { container } = render(
+        <Sparkline showTrend color="rgb(255, 0, 0)" data={[1, 2, 3, 4, 5]} />
+      )
+
+      const polyline = container.querySelector("polyline")
+      expect(polyline).toHaveAttribute("stroke", "rgb(255, 0, 0)")
+    })
+  })
+
+  describe("Dots", () => {
+    it("shows all dots when showDots is true", () => {
+      const { container } = render(
+        <Sparkline showDots data={[1, 2, 3, 4, 5]} />
+      )
+
+      const circles = container.querySelectorAll("circle")
+      expect(circles.length).toBe(5)
+    })
+
+    it("shows only end dot when showEndDot is true", () => {
+      const { container } = render(
+        <Sparkline showEndDot data={[1, 2, 3, 4, 5]} />
+      )
+
+      const circles = container.querySelectorAll("circle")
+      expect(circles.length).toBe(1)
+    })
+
+    it("showDots takes precedence over showEndDot", () => {
+      const { container } = render(
+        <Sparkline showDots showEndDot data={[1, 2, 3, 4, 5]} />
+      )
+
+      const circles = container.querySelectorAll("circle")
+      expect(circles.length).toBe(5)
+    })
+  })
+
+  describe("Stroke Width", () => {
+    it("applies default stroke width", () => {
+      const { container } = render(<Sparkline data={[1, 2, 3]} />)
+
+      const polyline = container.querySelector("polyline")
+      expect(polyline).toHaveAttribute("stroke-width", "1.5")
+    })
+
+    it("applies custom stroke width", () => {
+      const { container } = render(
+        <Sparkline data={[1, 2, 3]} strokeWidth={3} />
+      )
+
+      const polyline = container.querySelector("polyline")
+      expect(polyline).toHaveAttribute("stroke-width", "3")
+    })
+  })
+
+  describe("Edge Cases", () => {
+    it("handles single data point", () => {
+      const { container } = render(<Sparkline data={[42]} />)
+
+      expect(screen.getByRole("img")).toBeInTheDocument()
+      expect(container.querySelector("polyline")).toBeInTheDocument()
+    })
+
+    it("handles two data points", () => {
+      const { container } = render(<Sparkline data={[1, 5]} />)
+
+      expect(screen.getByRole("img")).toBeInTheDocument()
+      expect(container.querySelector("polyline")).toBeInTheDocument()
+    })
+
+    it("handles all same values", () => {
+      const { container } = render(<Sparkline data={[5, 5, 5, 5, 5]} />)
+
+      expect(screen.getByRole("img")).toBeInTheDocument()
+      expect(container.querySelector("polyline")).toBeInTheDocument()
+    })
+
+    it("handles negative values", () => {
+      const { container } = render(<Sparkline data={[-5, -2, 0, 3, 7]} />)
+
+      expect(screen.getByRole("img")).toBeInTheDocument()
+      expect(container.querySelector("polyline")).toBeInTheDocument()
+    })
+
+    it("handles decimal values", () => {
+      const { container } = render(
+        <Sparkline data={[1.5, 2.7, 3.2, 4.8, 5.1]} />
+      )
+
+      expect(screen.getByRole("img")).toBeInTheDocument()
+      expect(container.querySelector("polyline")).toBeInTheDocument()
+    })
+  })
+})