@etus/ui 0.1.0

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

@@ -0,0 +1,261 @@
+# PieChart
+
+## Visão Geral
+
+O PieChart e um componente de visualizacao de dados que exibe proporcoes como fatias de um circulo. Cada fatia representa uma categoria e seu tamanho e proporcional ao valor. Ideal para mostrar composicao de um todo.
+
+### Classificacao Atomica
+- **Categoria**: Organisms
+- **Subcategoria**: Data Display / Charts
+
+### Casos de Uso Comuns
+- Distribuicao de mercado
+- Composicao de portfolio
+- Alocacao de recursos
+- Distribuicao demografica
+- Analise de trafego por fonte
+- Composicao de vendas por categoria
+
+### Relacao com Outros Componentes
+- **Chart**: Componente base com ChartContainer
+- **ChartLegend**: Essencial para identificar fatias
+- **GaugeChart**: Para valor unico como proporcao
+- **Card**: Container comum
+
+## Design Specs
+
+### Variantes
+
+| Variante | Descricao |
+|----------|-----------|
+| `pie` | Circulo completo preenchido |
+| `donut` | Circulo com buraco central |
+| `semi` | Semicirculo (180 graus) |
+
+### Parametros de Donut
+
+| Param | Descricao |
+|-------|-----------|
+| `innerRadius` | Raio interno (ex: 60 para donut) |
+| `outerRadius` | Raio externo (ex: 80) |
+| `paddingAngle` | Espaco entre fatias |
+| `cornerRadius` | Arredondamento das fatias |
+
+### Estados
+
+- **Default**: Fatias renderizadas
+- **Hover**: Fatia destacada com tooltip
+- **Active**: Fatia expandida
+
+### Tokens de Design
+
+#### Cores
+- Fill: `var(--color-{category})` por fatia
+- Stroke: Transparente ou branco
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `data` | `Array<{name: string, value: number, fill?: string}>` | - | Dados |
+| `config` | `ChartConfig` | - | Configuracao de cores |
+| `dataKey` | `string` | `"value"` | Chave do valor |
+| `nameKey` | `string` | `"name"` | Chave do nome |
+| `innerRadius` | `number` | `0` | Raio interno (0 = pie, >0 = donut) |
+| `outerRadius` | `number` | `80` | Raio externo |
+| `paddingAngle` | `number` | `0` | Angulo entre fatias |
+| `cornerRadius` | `number` | `0` | Arredondamento |
+| `showLabel` | `boolean` | `false` | Mostrar labels nas fatias |
+| `showLegend` | `boolean` | `true` | Mostrar legenda |
+| `showTooltip` | `boolean` | `true` | Mostrar tooltip |
+
+## Exemplos
+
+### Uso Básico
+
+```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%"
+          outerRadius={80}
+        />
+      </PieChart>
+    </ChartContainer>
+  )
+}
+```
+
+### Donut Chart
+
+```tsx
+function DonutChartExample() {
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <PieChart>
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <Pie
+          data={data}
+          dataKey="value"
+          nameKey="name"
+          cx="50%"
+          cy="50%"
+          innerRadius={60}
+          outerRadius={80}
+          paddingAngle={2}
+        />
+      </PieChart>
+    </ChartContainer>
+  )
+}
+```
+
+### Com Label Central (Donut)
+
+```tsx
+function DonutWithLabel() {
+  const total = data.reduce((sum, item) => sum + item.value, 0)
+
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <PieChart>
+        <Pie
+          data={data}
+          dataKey="value"
+          nameKey="name"
+          cx="50%"
+          cy="50%"
+          innerRadius={60}
+          outerRadius={80}
+        />
+        <text
+          x="50%"
+          y="50%"
+          textAnchor="middle"
+          dominantBaseline="middle"
+          className="fill-foreground text-3xl font-bold"
+        >
+          {total}
+        </text>
+        <text
+          x="50%"
+          y="55%"
+          textAnchor="middle"
+          dominantBaseline="middle"
+          className="fill-muted-foreground text-sm"
+        >
+          Total
+        </text>
+      </PieChart>
+    </ChartContainer>
+  )
+}
+```
+
+### Com Labels nas Fatias
+
+```tsx
+import { LabelList } from 'recharts'
+
+function PieChartWithLabels() {
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <PieChart>
+        <Pie
+          data={data}
+          dataKey="value"
+          nameKey="name"
+          cx="50%"
+          cy="50%"
+          outerRadius={100}
+          label={({ name, percent }) => `${name} ${(percent * 100).toFixed(0)}%`}
+          labelLine={true}
+        />
+      </PieChart>
+    </ChartContainer>
+  )
+}
+```
+
+## Acessibilidade (A11y)
+
+### Recomendacoes
+- Sempre incluir legenda (fatias sao dificeis de distinguir)
+- Usar cores com alto contraste entre si
+- Limitar a 5-7 fatias para clareza
+- Fornecer dados tabulares como alternativa
+
+### ARIA
+- Container com `aria-label` descritivo
+- Legenda acessivel via teclado
+
+### Limitacoes
+- Graficos de pizza sao notoriamente dificeis para pessoas com daltonismo
+- Considerar bar chart como alternativa mais acessivel
+
+## Testes
+
+```typescript
+import { render, screen } from '@testing-library/react'
+import { ChartContainer } from '../Chart'
+import { PieChart, Pie } from 'recharts'
+
+describe('PieChart', () => {
+  it('renders pie slices', () => {
+    const data = [{ name: 'A', value: 100 }]
+    const config = { a: { label: 'A', color: '#000' } }
+
+    render(
+      <ChartContainer config={config}>
+        <PieChart>
+          <Pie data={data} dataKey="value" />
+        </PieChart>
+      </ChartContainer>
+    )
+
+    expect(screen.getByRole('presentation')).toBeInTheDocument()
+  })
+})
+```
+
+## Referências
+
+- [Recharts PieChart](https://recharts.org/en-US/api/PieChart)
+- [Shadcn UI Charts](https://ui.shadcn.com/docs/components/chart)
+- [Data Visualization Best Practices](https://www.nngroup.com/articles/pie-charts/)

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

@@ -0,0 +1,2 @@
+export * from './PieChart'
+export type * from './PieChart.types'

package/src/components/data-display/ScatterChart/ScatterChart.tsx

@@ -0,0 +1,310 @@
+"use client"
+
+import type { ScatterChartProps, ScatterChartTooltipCallbackProps, ScatterChartTooltipIndicator } from "./ScatterChart.types"
+
+import * as React from "react"
+import {
+  CartesianGrid,
+  Label,
+  ScatterChart as RechartsScatterChart,
+  Scatter,
+  XAxis,
+  YAxis,
+  ZAxis,
+} from "recharts"
+
+import { cn } from "../../../lib/utils"
+import {
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  ChartTooltip,
+  ChartTooltipContent,
+} from "../Chart"
+
+/**
+ * Internal tooltip content wrapper that calls the tooltipCallback
+ */
+interface TooltipContentWithCallbackProps {
+  tooltipCallback?: (props: ScatterChartTooltipCallbackProps) => void
+  tooltipIndicator: ScatterChartTooltipIndicator
+  xAxisKey: string
+  yAxisKey: string
+  zAxisKey?: string
+}
+
+function TooltipContentWithCallback({
+  tooltipCallback,
+  tooltipIndicator,
+  xAxisKey,
+  yAxisKey,
+  zAxisKey,
+  ...props
+}: TooltipContentWithCallbackProps & Record<string, unknown>) {
+  const prevActiveRef = React.useRef<boolean>(false)
+  const { active = false, payload } = props as { active?: boolean; payload?: { payload: Record<string, unknown> }[] }
+
+  // Use effect to call callback when active state changes
+  // This is an intentional callback pattern for tooltip state changes
+  /* eslint-disable react-you-might-not-need-an-effect/no-pass-data-to-parent */
+  React.useEffect(() => {
+    if (tooltipCallback && active !== prevActiveRef.current) {
+      prevActiveRef.current = active
+      tooltipCallback({
+        active,
+        payload: payload?.map((p) => ({
+          payload: p.payload,
+          x: p.payload[xAxisKey] as number,
+          y: p.payload[yAxisKey] as number,
+          z: zAxisKey ? p.payload[zAxisKey] as number : undefined,
+        })),
+      })
+    }
+  }, [active, payload, tooltipCallback, xAxisKey, yAxisKey, zAxisKey])
+  /* eslint-enable react-you-might-not-need-an-effect/no-pass-data-to-parent */
+
+  return <ChartTooltipContent indicator={tooltipIndicator} {...props} />
+}
+
+/**
+ * ScatterChart - Data visualization for correlation and distribution
+ *
+ * Displays data points on a two-dimensional plane, ideal for showing
+ * relationships between variables, identifying clusters, and
+ * detecting outliers.
+ *
+ * @example
+ * ```tsx
+ * const data = [
+ *   { x: 100, y: 200, name: "A" },
+ *   { x: 120, y: 100, name: "B" },
+ *   { x: 170, y: 300, name: "C" },
+ * ]
+ *
+ * const config = {
+ *   series1: { label: "Series 1", color: "hsl(var(--chart-1))" },
+ * }
+ *
+ * <ScatterChart
+ *   config={config}
+ *   series={[{ dataKey: "series1", data }]}
+ *   xAxisKey="x"
+ *   yAxisKey="y"
+ * />
+ * ```
+ */
+export function ScatterChart({
+  autoMinValue = false,
+  className,
+  config,
+  enableLegendSlider = false,
+  gridDashArray = "3 3",
+  intervalType,
+  legendPosition = "bottom",
+  maxXValue,
+  maxYValue,
+  minXValue,
+  minYValue,
+  onClick,
+  rotateLabelX,
+  series,
+  shape = "circle",
+  showGrid = true,
+  showLegend = false,
+  showOpacity = false,
+  showTooltip = true,
+  showXAxis = true,
+  showYAxis = true,
+  size = 60,
+  sizeRange = [60, 400],
+  startEndOnly = false,
+  tickGap,
+  tooltipCallback,
+  tooltipIndicator = "dot",
+  valueFormatter,
+  xAxisKey,
+  xAxisLabel,
+  xAxisTickFormatter,
+  yAxisKey,
+  yAxisLabel,
+  yAxisTickFormatter,
+  yAxisWidth,
+  zAxisKey,
+  ...props
+}: ScatterChartProps) {
+  // Handle point click - Recharts passes any-typed data
+  /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access */
+  const handleClick = React.useCallback((data: any) => {
+    if (!onClick || !data) return
+    onClick({
+      payload: data.payload ?? data,
+      x: data[xAxisKey] ?? data.x,
+      y: data[yAxisKey] ?? data.y,
+      z: zAxisKey ? data[zAxisKey] : undefined,
+    })
+  }, [onClick, xAxisKey, yAxisKey, zAxisKey])
+  /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access */
+
+  // Calculate X-axis domain
+  const xDomain = React.useMemo(() => {
+    const min = minXValue ?? (autoMinValue ? "auto" : "dataMin")
+    const max = maxXValue ?? "dataMax"
+    return [min, max] as const
+  }, [autoMinValue, maxXValue, minXValue])
+
+  // Calculate Y-axis domain
+  const yDomain = React.useMemo(() => {
+    const min = minYValue ?? (autoMinValue ? "auto" : "dataMin")
+    const max = maxYValue ?? "dataMax"
+    return [min, max] as const
+  }, [autoMinValue, maxYValue, minYValue])
+
+  // Calculate X-axis ticks for startEndOnly
+  const xAxisTicks = React.useMemo(() => {
+    if (!startEndOnly) return
+    // For scatter charts, we need to find min/max from all series
+    const allXValues: number[] = []
+    for (const s of series) {
+      for (const point of s.data) {
+        const xVal = point[xAxisKey]
+        if (typeof xVal === "number") {
+          allXValues.push(xVal)
+        }
+      }
+    }
+    if (allXValues.length < 2) return
+    const minX = Math.min(...allXValues)
+    const maxX = Math.max(...allXValues)
+    return [minX, maxX]
+  }, [series, startEndOnly, xAxisKey])
+
+  // Determine effective interval based on startEndOnly
+  const effectiveInterval = startEndOnly ? "preserveStartEnd" : intervalType
+
+  // Effective tick formatters (valueFormatter takes precedence)
+  const effectiveXFormatter = valueFormatter?.x ?? xAxisTickFormatter
+  const effectiveYFormatter = valueFormatter?.y ?? yAxisTickFormatter
+
+  return (
+    <div data-slot="scatter-chart" {...props}>
+      <ChartContainer
+        className={cn(className)}
+        config={config}
+      >
+        <RechartsScatterChart
+          accessibilityLayer
+          margin={{
+            left: yAxisLabel ? 20 : 12,
+            right: 12,
+            bottom: xAxisLabel ? 20 : 0,
+          }}
+        >
+          {showGrid && (
+            <CartesianGrid strokeDasharray={gridDashArray} />
+          )}
+
+          {showXAxis && (
+            <XAxis
+              angle={rotateLabelX}
+              axisLine={false}
+              dataKey={xAxisKey}
+              domain={xDomain}
+              interval={effectiveInterval}
+              minTickGap={tickGap}
+              name={xAxisKey}
+              textAnchor={rotateLabelX ? "end" : "middle"}
+              tickFormatter={effectiveXFormatter}
+              tickLine={false}
+              tickMargin={8}
+              ticks={xAxisTicks}
+              type="number"
+            >
+              {xAxisLabel && (
+                <Label offset={-5} position="insideBottom" value={xAxisLabel} />
+              )}
+            </XAxis>
+          )}
+
+          {showYAxis && (
+            <YAxis
+              axisLine={false}
+              dataKey={yAxisKey}
+              domain={yDomain}
+              name={yAxisKey}
+              tickFormatter={effectiveYFormatter}
+              tickLine={false}
+              tickMargin={8}
+              type="number"
+              width={yAxisWidth}
+            >
+              {yAxisLabel && (
+                <Label angle={-90} offset={-5} position="insideLeft" value={yAxisLabel} />
+              )}
+            </YAxis>
+          )}
+
+          {zAxisKey && (
+            <ZAxis dataKey={zAxisKey} name={zAxisKey} range={sizeRange} type="number" />
+          )}
+
+          {showTooltip && (
+            <ChartTooltip
+              content={
+                tooltipCallback
+                  ? <TooltipContentWithCallback
+                      tooltipCallback={tooltipCallback}
+                      tooltipIndicator={tooltipIndicator}
+                      xAxisKey={xAxisKey}
+                      yAxisKey={yAxisKey}
+                      zAxisKey={zAxisKey}
+                    />
+                  : <ChartTooltipContent indicator={tooltipIndicator} />
+              }
+              cursor={{ strokeDasharray: "3 3" }}
+            />
+          )}
+
+          {showLegend && (
+            <ChartLegend
+              align={legendPosition === "left" ? "left" : legendPosition === "right" ? "right" : "center"}
+              content={<ChartLegendContent enableSlider={enableLegendSlider} />}
+              layout={legendPosition === "left" || legendPosition === "right" ? "vertical" : "horizontal"}
+              verticalAlign={legendPosition === "top" ? "top" : legendPosition === "bottom" ? "bottom" : "middle"}
+            />
+          )}
+
+          {series.map((seriesConfig) => {
+            const {
+              data,
+              dataKey,
+              fill: seriesFill,
+              shape: seriesShape,
+              size: seriesSize,
+            } = seriesConfig
+
+            const fill = seriesFill ?? `var(--color-${dataKey})`
+
+            return (
+              <Scatter
+                key={dataKey}
+                data={data}
+                fill={fill}
+                fillOpacity={showOpacity ? 0.7 : 1}
+                name={dataKey}
+                shape={seriesShape ?? shape}
+                style={onClick ? { cursor: "pointer" } : undefined}
+                onClick={onClick ? handleClick : undefined}
+              >
+                {!zAxisKey && (
+                  <ZAxis range={[seriesSize ?? size, seriesSize ?? size]} />
+                )}
+              </Scatter>
+            )
+          })}
+        </RechartsScatterChart>
+      </ChartContainer>
+    </div>
+  )
+}
+
+ScatterChart.displayName = "ScatterChart"