@etus/ui 0.1.1 → 0.1.3

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

@@ -1,674 +0,0 @@
-# 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

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