@etus/ui 0.1.0

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

@@ -0,0 +1,674 @@
+# Chart
+
+## Visão Geral
+
+O Chart e um sistema de componentes para visualizacao de dados construido sobre o Recharts. Fornece uma API consistente e acessivel para criar graficos responsivos com suporte a temas, tooltips personalizados e legendas. E o componente base para todos os tipos de graficos especializados (AreaChart, BarChart, LineChart, etc.).
+
+### Classificacao Atomica
+
+- **Categoria**: Organisms
+- **Subcategoria**: Data Display / Visualization
+
+### Casos de Uso Comuns
+
+- Dashboards com metricas de performance
+- Relatorios de vendas e financeiros
+- Monitoramento de sistemas em tempo real
+- Analise de tendencias temporais
+- Comparacao de dados entre periodos
+- Visualizacao de KPIs
+
+### Relacao com Outros Componentes
+
+- **AreaChart**: Especializa Chart para graficos de area
+- **BarChart**: Especializa Chart para graficos de barras
+- **LineChart**: Especializa Chart para graficos de linha
+- **PieChart**: Especializa Chart para graficos de pizza
+- **ChartLegend**: Legenda complementar para graficos
+- **Card**: Container comum para graficos
+- **KPICard**: Combina metricas com mini graficos
+
+## Design Specs
+
+### Componentes do Sistema
+
+O sistema Chart e composto por:
+
+1. **ChartContainer**: Container responsivo com provider de contexto
+2. **ChartTooltip**: Tooltip padrao do Recharts
+3. **ChartTooltipContent**: Conteudo customizado do tooltip
+4. **ChartLegend**: Legenda padrao do Recharts
+5. **ChartLegendContent**: Conteudo customizado da legenda
+6. **ChartStyle**: Injeta CSS dinamico para cores
+
+### Configuracao (ChartConfig)
+
+```typescript
+type ChartConfig = {
+  [key: string]: {
+    label?: React.ReactNode;
+    icon?: React.ComponentType;
+  } & (
+    | { color?: string; theme?: never }
+    | { color?: never; theme: Record<"light" | "dark", string> }
+  );
+};
+```
+
+### Indicadores de Tooltip
+
+- **dot**: Circulo pequeno (padrao)
+- **line**: Linha vertical
+- **dashed**: Linha tracejada
+
+### Estados
+
+- **Default**: Grafico renderizado com dados
+- **Hover**: Tooltip visivel ao passar sobre pontos de dados
+- **Empty**: Estado sem dados (requer tratamento customizado)
+- **Loading**: Skeleton ou spinner (implementacao externa)
+
+### Tokens de Design
+
+#### Cores
+
+- Background (tooltip): `bg-background`
+- Border (tooltip): `border-border/50`
+- Text: `text-foreground`
+- Muted Text: `text-muted-foreground`
+- Grid Lines: `stroke-border/50`
+
+#### Espacamento
+
+- Tooltip Padding: `px-2.5 py-1.5`
+- Legend Padding: `pt-3` (bottom) ou `pb-3` (top)
+- Gap entre items: `gap-1.5`
+
+#### Tipografia
+
+- Font Size: `text-xs`
+- Value Font: `font-mono font-medium tabular-nums`
+
+#### Bordas e Arredondamento
+
+- Tooltip Border Radius: `rounded-lg`
+- Indicator Border Radius: `rounded-[2px]`
+
+#### Motion e Transicoes
+
+- Tooltip: Animacao padrao do Recharts
+
+### Padrão de Tokens com Tailwind v4
+
+O componente Chart utiliza tokens de design definidos em `@etus/tokens`. No Tailwind v4, variáveis CSS que contêm cores OKLCH precisam do prefixo `color:` para serem interpretadas corretamente.
+
+#### Tokens Disponíveis
+
+```css
+/* Data Series Colors */
+--color-chrome
+--color-safari
+--color-firefox
+--color-edge
+--color-other
+--color-desktop
+--color-mobile
+
+/* Tooltip */
+--chart-tooltip-bg
+--chart-tooltip-border
+--chart-tooltip-radius
+--chart-tooltip-shadow
+--chart-tooltip-padding-x
+--chart-tooltip-padding-y
+--chart-tooltip-gap
+--chart-tooltip-min-width
+--chart-tooltip-text
+
+/* Legend */
+--chart-legend-gap
+--chart-legend-padding
+
+/* Indicator */
+--chart-indicator-dot-size
+--chart-indicator-line-width
+```
+
+#### Sintaxe Tailwind v4
+
+```tsx
+// ✅ CORRETO - cores precisam do prefixo color:
+bg-[color:var(--chart-tooltip-bg)]
+border-[color:var(--chart-tooltip-border)]
+fill-[color:var(--color-desktop)]
+stroke-[color:var(--color-mobile)]
+
+// ✅ CORRETO - dimensões não precisam de prefixo
+px-[var(--chart-tooltip-padding-x)]
+py-[var(--chart-tooltip-padding-y)]
+gap-[var(--chart-tooltip-gap)]
+min-w-[var(--chart-tooltip-min-width)]
+rounded-[var(--chart-tooltip-radius)]
+text-[length:var(--chart-tooltip-text)]
+size-[var(--chart-indicator-dot-size)]
+
+// ✅ CORRETO - em ChartConfig use diretamente
+const chartConfig: ChartConfig = {
+  desktop: {
+    label: "Desktop",
+    color: "var(--color-desktop)", // ou oklch(...)
+  },
+}
+
+// ❌ INCORRETO - nunca usar hsl() ou omitir color:
+bg-[hsl(var(--chart-tooltip-bg))]
+bg-[var(--chart-tooltip-bg)]
+```
+
+#### Por que usar `color:`?
+
+O Tailwind v4 usa Lightning CSS que requer type hints para valores ambíguos. Cores OKLCH como `oklch(81.06% 0.2032 150.12)` precisam do prefixo `color:` para serem corretamente interpretadas como cores e não como valores genéricos.
+
+### Consideracoes de Responsividade
+
+- **Aspecto**: `aspect-video` por padrao (16:9)
+- **ResponsiveContainer**: Adapta automaticamente ao container pai
+- **Container Queries**: Use `@container` para ajustar legenda e tooltips
+
+## API
+
+### ChartContainer
+
+| Prop        | Tipo          | Padrao         | Descricao                                    |
+| ----------- | ------------- | -------------- | -------------------------------------------- |
+| `config`    | `ChartConfig` | -              | Configuracao de cores e labels (obrigatorio) |
+| `id`        | `string`      | auto-generated | ID unico para CSS scoped                     |
+| `className` | `string`      | `""`           | Classes Tailwind adicionais                  |
+| `children`  | `ReactNode`   | -              | Grafico Recharts como filho                  |
+
+### ChartTooltipContent
+
+| Prop             | Tipo                          | Padrao  | Descricao                    |
+| ---------------- | ----------------------------- | ------- | ---------------------------- |
+| `active`         | `boolean`                     | -       | Se o tooltip esta ativo      |
+| `payload`        | `array`                       | -       | Dados do ponto hovereado     |
+| `indicator`      | `"dot" \| "line" \| "dashed"` | `"dot"` | Estilo do indicador          |
+| `hideLabel`      | `boolean`                     | `false` | Oculta o label principal     |
+| `hideIndicator`  | `boolean`                     | `false` | Oculta o indicador de cor    |
+| `label`          | `string`                      | -       | Label customizado            |
+| `labelFormatter` | `function`                    | -       | Funcao para formatar o label |
+| `formatter`      | `function`                    | -       | Funcao para formatar valores |
+| `nameKey`        | `string`                      | -       | Chave para nome no payload   |
+| `labelKey`       | `string`                      | -       | Chave para label no payload  |
+
+### ChartLegendContent
+
+| Prop            | Tipo                | Padrao     | Descricao                   |
+| --------------- | ------------------- | ---------- | --------------------------- |
+| `payload`       | `array`             | -          | Items da legenda            |
+| `verticalAlign` | `"top" \| "bottom"` | `"bottom"` | Alinhamento vertical        |
+| `hideIcon`      | `boolean`           | `false`    | Oculta icones/indicadores   |
+| `nameKey`       | `string`            | -          | Chave para nome no payload  |
+| `className`     | `string`            | `""`       | Classes Tailwind adicionais |
+
+### Hook: useChart
+
+```typescript
+function useChart(): {
+  config: ChartConfig;
+};
+```
+
+Deve ser usado dentro de `ChartContainer`.
+
+### Interfaces TypeScript
+
+```typescript
+// Temas suportados
+const THEMES = { light: "", dark: ".dark" } as const;
+
+// Configuracao do grafico
+export type ChartConfig = {
+  [k in string]: {
+    label?: React.ReactNode;
+    icon?: React.ComponentType;
+  } & (
+    | { color?: string; theme?: never }
+    | { color?: never; theme: Record<keyof typeof THEMES, string> }
+  );
+};
+
+// Props do ChartContainer
+interface ChartContainerProps extends React.ComponentProps<"div"> {
+  config: ChartConfig;
+  children: React.ReactNode;
+}
+
+// Props do ChartTooltipContent
+interface ChartTooltipContentProps {
+  active?: boolean;
+  payload?: Array<{
+    name?: string;
+    value?: number;
+    dataKey?: string;
+    color?: string;
+    payload?: Record<string, unknown>;
+  }>;
+  indicator?: "line" | "dot" | "dashed";
+  hideLabel?: boolean;
+  hideIndicator?: boolean;
+  label?: string;
+  labelFormatter?: (value: unknown, payload: unknown[]) => React.ReactNode;
+  formatter?: (
+    value: number,
+    name: string,
+    item: unknown,
+    index: number,
+    payload: unknown,
+  ) => React.ReactNode;
+  nameKey?: string;
+  labelKey?: string;
+  className?: string;
+  labelClassName?: string;
+  color?: string;
+}
+```
+
+### Comparacao com Referencias
+
+| Feature     | ETUS     | Recharts | Tremor | Nivo    |
+| ----------- | -------- | -------- | ------ | ------- |
+| Responsivo  | Sim      | Sim      | Sim    | Sim     |
+| Theming     | Sim      | Manual   | Sim    | Sim     |
+| TypeScript  | Sim      | Sim      | Sim    | Sim     |
+| SSR         | Sim\*    | Sim\*    | Sim    | Parcial |
+| Animations  | Recharts | Nativo   | Nativo | Nativo  |
+| Bundle size | ~100KB   | ~100KB   | ~150KB | ~200KB  |
+
+\*Requer configuracao especial para SSR
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+
+Graficos sao inerentemente visuais e requerem cuidado especial:
+
+- Fornecer `aria-label` descritivo no container
+- Usar `aria-describedby` para descricoes detalhadas
+- Considerar tabela de dados alternativa para screen readers
+
+### Navegacao por Teclado
+
+Recharts tem suporte limitado a navegacao por teclado. Recomendacoes:
+
+- Fornecer dados em formato de tabela acessivel
+- Usar focus indicators claros
+- Considerar visualizacoes alternativas
+
+### Contraste e Legibilidade
+
+- Cores devem ter contraste minimo de 3:1 entre si
+- Evitar depender apenas de cor para diferenciar series
+- Usar patterns ou labels quando possivel
+
+### Tecnologias Assistivas
+
+- Fornecer resumo textual dos dados
+- Considerar sonificacao de dados
+- Oferecer download de dados tabulares
+
+### Conformidade WCAG
+
+- **1.1.1** Conteudo nao textual: Fornecer alternativa textual
+- **1.4.1** Uso de cor: Nao depender apenas de cor
+- **1.4.11** Contraste nao textual: 3:1 para elementos graficos
+
+## Exemplos
+
+### Uso Basico com AreaChart
+
+```tsx
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from "@etus/ui";
+import { Area, AreaChart, XAxis, YAxis } from "recharts";
+
+const data = [
+  { month: "Jan", desktop: 186 },
+  { month: "Feb", desktop: 305 },
+  { month: "Mar", desktop: 237 },
+  { month: "Apr", desktop: 73 },
+  { month: "May", desktop: 209 },
+  { month: "Jun", desktop: 214 },
+];
+
+const chartConfig: ChartConfig = {
+  desktop: {
+    label: "Desktop",
+    color: "hsl(var(--chart-1))",
+  },
+};
+
+function AreaChartExample() {
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <AreaChart data={data}>
+        <XAxis dataKey="month" />
+        <YAxis />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <Area
+          type="monotone"
+          dataKey="desktop"
+          stroke="var(--color-desktop)"
+          fill="var(--color-desktop)"
+          fillOpacity={0.3}
+        />
+      </AreaChart>
+    </ChartContainer>
+  );
+}
+```
+
+### BarChart com Multiplas Series
+
+```tsx
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  ChartLegend,
+  ChartLegendContent,
+  type ChartConfig,
+} from "@etus/ui";
+import { Bar, BarChart, XAxis, YAxis } from "recharts";
+
+const data = [
+  { month: "Jan", desktop: 186, mobile: 80 },
+  { month: "Feb", desktop: 305, mobile: 200 },
+  { month: "Mar", desktop: 237, mobile: 120 },
+];
+
+const chartConfig: ChartConfig = {
+  desktop: {
+    label: "Desktop",
+    color: "hsl(var(--chart-1))",
+  },
+  mobile: {
+    label: "Mobile",
+    color: "hsl(var(--chart-2))",
+  },
+};
+
+function BarChartExample() {
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <BarChart data={data}>
+        <XAxis dataKey="month" />
+        <YAxis />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <ChartLegend content={<ChartLegendContent />} />
+        <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
+        <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
+      </BarChart>
+    </ChartContainer>
+  );
+}
+```
+
+### LineChart com Theme-aware Colors
+
+```tsx
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from "@etus/ui";
+import { Line, LineChart, XAxis, YAxis } from "recharts";
+
+const chartConfig: ChartConfig = {
+  visitors: {
+    label: "Visitantes",
+    theme: {
+      light: "hsl(220 70% 50%)",
+      dark: "hsl(220 70% 70%)",
+    },
+  },
+};
+
+function ThemedLineChart() {
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <LineChart data={data}>
+        <XAxis dataKey="date" />
+        <YAxis />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <Line
+          type="monotone"
+          dataKey="visitors"
+          stroke="var(--color-visitors)"
+          strokeWidth={2}
+        />
+      </LineChart>
+    </ChartContainer>
+  );
+}
+```
+
+### Tooltip Customizado
+
+```tsx
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from "@etus/ui";
+import { Line, LineChart } from "recharts";
+
+function CustomTooltipExample() {
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <LineChart data={data}>
+        <ChartTooltip
+          content={
+            <ChartTooltipContent
+              indicator="line"
+              labelFormatter={(value) => `Data: ${value}`}
+              formatter={(value, name) => (
+                <span className="font-bold text-primary">
+                  {value.toLocaleString("pt-BR")} unidades
+                </span>
+              )}
+            />
+          }
+        />
+        <Line dataKey="value" />
+      </LineChart>
+    </ChartContainer>
+  );
+}
+```
+
+### Grafico com Icones na Config
+
+```tsx
+import {
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  type ChartConfig,
+} from "@etus/ui";
+import { Monitor, Smartphone } from "lucide-react";
+
+const chartConfig: ChartConfig = {
+  desktop: {
+    label: "Desktop",
+    icon: Monitor,
+    color: "hsl(var(--chart-1))",
+  },
+  mobile: {
+    label: "Mobile",
+    icon: Smartphone,
+    color: "hsl(var(--chart-2))",
+  },
+};
+
+function IconLegendExample() {
+  return (
+    <ChartContainer config={chartConfig}>
+      <BarChart data={data}>
+        <ChartLegend content={<ChartLegendContent />} />
+        <Bar dataKey="desktop" fill="var(--color-desktop)" />
+        <Bar dataKey="mobile" fill="var(--color-mobile)" />
+      </BarChart>
+    </ChartContainer>
+  );
+}
+```
+
+### PieChart com Legenda
+
+```tsx
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  ChartLegend,
+  ChartLegendContent,
+  type ChartConfig,
+} from "@etus/ui";
+import { Pie, PieChart, Cell } from "recharts";
+
+const data = [
+  { name: "Chrome", value: 275, fill: "var(--color-chrome)" },
+  { name: "Safari", value: 200, fill: "var(--color-safari)" },
+  { name: "Firefox", value: 187, fill: "var(--color-firefox)" },
+  { name: "Edge", value: 173, fill: "var(--color-edge)" },
+  { name: "Other", value: 90, fill: "var(--color-other)" },
+];
+
+const chartConfig: ChartConfig = {
+  chrome: { label: "Chrome", color: "hsl(var(--chart-1))" },
+  safari: { label: "Safari", color: "hsl(var(--chart-2))" },
+  firefox: { label: "Firefox", color: "hsl(var(--chart-3))" },
+  edge: { label: "Edge", color: "hsl(var(--chart-4))" },
+  other: { label: "Other", color: "hsl(var(--chart-5))" },
+};
+
+function PieChartExample() {
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <PieChart>
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <ChartLegend content={<ChartLegendContent />} />
+        <Pie
+          data={data}
+          dataKey="value"
+          nameKey="name"
+          cx="50%"
+          cy="50%"
+          innerRadius={60}
+          outerRadius={80}
+        />
+      </PieChart>
+    </ChartContainer>
+  );
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+
+- Renderizacao do ChartContainer
+- Contexto ChartContext funcionando
+- ChartConfig aplicado corretamente
+
+#### Testes de Integracao
+
+- Grafico completo com tooltip
+- Legenda com items corretos
+- Theming light/dark
+
+#### Testes de Acessibilidade
+
+- Alternativas textuais presentes
+- Contraste de cores adequado
+
+### Exemplos de Codigo
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { ChartContainer, type ChartConfig } from './Chart'
+import { BarChart, Bar } from 'recharts'
+
+const chartConfig: ChartConfig = {
+  value: {
+    label: "Value",
+    color: "#000",
+  },
+}
+
+describe('ChartContainer', () => {
+  it('renders with config', () => {
+    render(
+      <ChartContainer config={chartConfig}>
+        <BarChart data={[{ value: 10 }]}>
+          <Bar dataKey="value" />
+        </BarChart>
+      </ChartContainer>
+    )
+
+    expect(screen.getByRole('presentation')).toBeInTheDocument()
+  })
+
+  it('applies data-chart attribute', () => {
+    const { container } = render(
+      <ChartContainer config={chartConfig} id="test-chart">
+        <BarChart data={[{ value: 10 }]}>
+          <Bar dataKey="value" />
+        </BarChart>
+      </ChartContainer>
+    )
+
+    expect(container.querySelector('[data-chart="chart-test-chart"]')).toBeTruthy()
+  })
+
+  it('injects CSS variables for colors', () => {
+    const { container } = render(
+      <ChartContainer config={chartConfig}>
+        <BarChart data={[{ value: 10 }]}>
+          <Bar dataKey="value" />
+        </BarChart>
+      </ChartContainer>
+    )
+
+    const style = container.querySelector('style')
+    expect(style?.innerHTML).toContain('--color-value')
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Construido sobre Recharts para graficos robustos
+- Usa Context API para compartilhar config entre componentes
+- CSS variables dinamicas para cores por tema
+- `data-slot="chart"` para identificacao
+- Requer `use client` em Next.js
+
+## Referências
+
+- [Recharts Documentation](https://recharts.org/en-US/)
+- [Shadcn UI Charts](https://ui.shadcn.com/docs/components/chart)
+- [Tremor Charts](https://www.tremor.so/docs/visualizations/overview)
+- [W3C SVG Accessibility](https://www.w3.org/TR/SVG-access/)

package/src/components/data-display/Chart/index.ts

@@ -0,0 +1 @@
+export * from './Chart'