@etus/ui 0.1.0

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

@@ -0,0 +1,305 @@
+"use client"
+
+import type {
+  BarChartEventProps,
+  BarChartProps,
+  BarChartSeriesConfig,
+  BarChartTooltipCallbackProps,
+} from "./BarChart.types"
+
+import * as React from "react"
+import {
+  Bar,
+  CartesianGrid,
+  Label,
+  BarChart as RechartsBarChart,
+  XAxis,
+  YAxis,
+} from "recharts"
+
+import { cn } from "../../../lib/utils"
+import {
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  ChartTooltip,
+  ChartTooltipContent,
+} from "../Chart"
+
+/**
+ * Normalize series to BarChartSeriesConfig format
+ */
+function normalizeSeriesConfig(
+  series: (BarChartSeriesConfig | string)[]
+): BarChartSeriesConfig[] {
+  return series.map((s) =>
+    typeof s === "string" ? { dataKey: s } : s
+  )
+}
+
+/**
+ * BarChart - Data visualization component for categorical comparisons
+ *
+ * Displays quantitative values as rectangular bars. The height or width
+ * of bars is proportional to the values they represent. Ideal for
+ * comparing values between categories.
+ *
+ * @example
+ * ```tsx
+ * const data = [
+ *   { month: "Jan", desktop: 186, mobile: 80 },
+ *   { month: "Feb", desktop: 305, mobile: 200 },
+ * ]
+ *
+ * const config = {
+ *   desktop: { label: "Desktop", color: "hsl(var(--chart-1))" },
+ *   mobile: { label: "Mobile", color: "hsl(var(--chart-2))" },
+ * }
+ *
+ * <BarChart
+ *   data={data}
+ *   config={config}
+ *   xAxisKey="month"
+ *   series={["desktop", "mobile"]}
+ * />
+ * ```
+ */
+export function BarChart({
+  allowDecimals = true,
+  autoMinValue = false,
+  barCategoryGap,
+  barGap = 4,
+  className,
+  config,
+  customTooltip,
+  data,
+  enableLegendSlider = false,
+  gridDashArray = "3 3",
+  intervalType,
+  layout = "vertical",
+  legendPosition = "bottom",
+  maxValue,
+  minValue,
+  onValueChange,
+  radius = 4,
+  series,
+  showGrid = true,
+  showLegend = false,
+  showTooltip = true,
+  showXAxis = true,
+  showYAxis = true,
+  startEndOnly = false,
+  tickGap,
+  tooltipCallback,
+  tooltipIndicator = "dot",
+  variant = "default",
+  xAxisKey,
+  xAxisLabel,
+  xAxisTickFormatter,
+  yAxisLabel,
+  yAxisTickFormatter,
+  yAxisWidth,
+  ...props
+}: BarChartProps) {
+  const normalizedSeries = normalizeSeriesConfig(series)
+  const isStacked = variant === "stacked" || variant === "stacked100"
+  const isHorizontal = layout === "horizontal"
+  const prevTooltipStateRef = React.useRef<boolean>(false)
+
+  // Handle bar click for onValueChange
+  const handleBarClick = React.useCallback(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (dataKey: string) => (data: any) => {
+      if (!onValueChange || !data?.payload) return
+      const payload = data.payload as Record<string, unknown>
+      const value = payload[dataKey]
+      onValueChange({
+        category: payload[xAxisKey],
+        dataKey,
+        payload,
+        value: typeof value === "number" ? value : 0,
+      })
+    },
+    [onValueChange, xAxisKey]
+  )
+
+  // Custom tooltip content wrapper for tooltipCallback
+  const TooltipContentWithCallback = React.useCallback(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (props: any) => {
+      const { active = false, label, payload } = props
+
+      // Call tooltipCallback when state changes
+      if (tooltipCallback && active !== prevTooltipStateRef.current) {
+        prevTooltipStateRef.current = active
+        tooltipCallback({
+          active,
+          label,
+          payload: payload?.map((p: { dataKey: string | number; value: number; payload: Record<string, unknown> }) => ({
+            dataKey: String(p.dataKey),
+            value: p.value,
+            payload: p.payload,
+          })),
+        })
+      }
+
+      return <ChartTooltipContent indicator={tooltipIndicator} {...props} />
+    },
+    [tooltipCallback, tooltipIndicator]
+  )
+
+  // Calculate value axis domain
+  const valueDomain = React.useMemo(() => {
+    const min = minValue ?? (autoMinValue ? "auto" : 0)
+    const max = maxValue ?? "auto"
+    return [min, max] as const
+  }, [autoMinValue, maxValue, minValue])
+
+  // Calculate category axis ticks for startEndOnly
+  const categoryTicks = React.useMemo(() => {
+    if (!startEndOnly || data.length < 2) return undefined
+    const first = data[0]
+    const last = data[data.length - 1]
+    if (!first || !last) return undefined
+    return [first[xAxisKey], last[xAxisKey]] as string[]
+  }, [data, startEndOnly, xAxisKey])
+
+  return (
+    <div data-slot="bar-chart" {...props}>
+      <ChartContainer
+        className={cn(className)}
+        config={config}
+      >
+        <RechartsBarChart
+          accessibilityLayer
+          barCategoryGap={barCategoryGap}
+          barGap={barGap}
+          data={data}
+          layout={isHorizontal ? "vertical" : "horizontal"}
+          margin={{
+            left: yAxisLabel ? 20 : 12,
+            right: 12,
+            bottom: xAxisLabel ? 20 : 0,
+          }}
+        >
+          {showGrid && (
+            <CartesianGrid
+              horizontal={!isHorizontal}
+              strokeDasharray={gridDashArray}
+              vertical={isHorizontal}
+            />
+          )}
+
+          {showXAxis && (
+            isHorizontal ? (
+              <XAxis
+                axisLine={false}
+                domain={valueDomain}
+                interval={intervalType}
+                minTickGap={tickGap}
+                tickFormatter={xAxisTickFormatter}
+                tickLine={false}
+                tickMargin={8}
+                type="number"
+              >
+                {xAxisLabel && (
+                  <Label offset={-5} position="insideBottom" value={xAxisLabel} />
+                )}
+              </XAxis>
+            ) : (
+              <XAxis
+                axisLine={false}
+                dataKey={xAxisKey}
+                interval={intervalType}
+                minTickGap={tickGap}
+                tickFormatter={xAxisTickFormatter}
+                tickLine={false}
+                tickMargin={8}
+                ticks={categoryTicks}
+              >
+                {xAxisLabel && (
+                  <Label offset={-5} position="insideBottom" value={xAxisLabel} />
+                )}
+              </XAxis>
+            )
+          )}
+
+          {showYAxis && (
+            isHorizontal ? (
+              <YAxis
+                axisLine={false}
+                dataKey={xAxisKey}
+                tickFormatter={yAxisTickFormatter}
+                tickLine={false}
+                tickMargin={8}
+                ticks={categoryTicks}
+                type="category"
+                width={yAxisWidth}
+              >
+                {yAxisLabel && (
+                  <Label angle={-90} offset={-5} position="insideLeft" value={yAxisLabel} />
+                )}
+              </YAxis>
+            ) : (
+              <YAxis
+                allowDecimals={allowDecimals}
+                axisLine={false}
+                domain={valueDomain}
+                tickFormatter={yAxisTickFormatter}
+                tickLine={false}
+                tickMargin={8}
+                width={yAxisWidth}
+              >
+                {yAxisLabel && (
+                  <Label angle={-90} offset={-5} position="insideLeft" value={yAxisLabel} />
+                )}
+              </YAxis>
+            )
+          )}
+
+          {showTooltip && (
+            <ChartTooltip
+              content={
+                customTooltip
+                  ?? (tooltipCallback
+                    ? <TooltipContentWithCallback />
+                    : <ChartTooltipContent indicator={tooltipIndicator} />)
+              }
+              cursor={false}
+            />
+          )}
+
+          {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"}
+            />
+          )}
+
+          {normalizedSeries.map((seriesConfig) => {
+            const { dataKey, radius: seriesRadius, stackId } = seriesConfig
+
+            const fill = `var(--color-${dataKey})`
+            const barRadius = seriesRadius ?? radius
+
+            return (
+              <Bar
+                key={dataKey}
+                dataKey={dataKey}
+                fill={fill}
+                onClick={onValueChange ? handleBarClick(dataKey) : undefined}
+                radius={barRadius}
+                stackId={isStacked ? "bar-stack" : stackId}
+                style={onValueChange ? { cursor: "pointer" } : undefined}
+              />
+            )
+          })}
+        </RechartsBarChart>
+      </ChartContainer>
+    </div>
+  )
+}
+
+BarChart.displayName = "BarChart"

package/src/components/data-display/BarChart/BarChart.types.ts

@@ -0,0 +1,145 @@
+import type { ChartConfig } from "../Chart"
+import type { ComponentPropsWithoutRef, ReactElement } from "react"
+
+/**
+ * Layout orientation for bar chart
+ */
+export type BarChartLayout = "horizontal" | "vertical"
+
+/**
+ * Visual variant for bar chart rendering
+ */
+export type BarChartVariant = "default" | "stacked100" | "stacked"
+
+/**
+ * Tooltip indicator style
+ */
+export type BarChartTooltipIndicator = "dashed" | "dot" | "line"
+
+/**
+ * Legend position
+ */
+export type BarChartLegendPosition = "bottom" | "left" | "right" | "top"
+
+/**
+ * X-axis interval type
+ */
+export type BarChartIntervalType = "equidistantPreserveStart" | "preserveEnd" | "preserveStart" | "preserveStartEnd" | number
+
+/**
+ * Event payload for onValueChange callback
+ */
+export interface BarChartEventProps {
+  /** The category value (categorical axis) */
+  category: unknown
+  /** The series key that was clicked */
+  dataKey: string
+  /** The full data point */
+  payload: Record<string, unknown>
+  /** The value of the clicked series */
+  value: number
+}
+
+/**
+ * Tooltip callback props
+ */
+export interface BarChartTooltipCallbackProps {
+  /** Whether the tooltip is active/visible */
+  active: boolean
+  /** The category label (categorical axis value) */
+  label?: string
+  /** Array of series data in the tooltip */
+  payload?: Array<{
+    dataKey: string
+    value: number
+    payload: Record<string, unknown>
+  }>
+}
+
+/**
+ * Configuration for a single series in the bar chart
+ */
+export interface BarChartSeriesConfig {
+  /** Data key from the data array */
+  dataKey: string
+  /** Optional custom fill color (defaults to config color) */
+  fill?: string
+  /** Optional custom radius for this series */
+  radius?: number
+  /** Stack ID for stacked charts (all series with same stackId are stacked) */
+  stackId?: string
+}
+
+/**
+ * Props for the BarChart component
+ */
+export interface BarChartProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  /** Allow decimals on value axis ticks */
+  allowDecimals?: boolean
+  /** Automatically calculate minimum value axis from data */
+  autoMinValue?: boolean
+  /** Gap between bar groups/categories (px or percentage) */
+  barCategoryGap?: number | string
+  /** Gap between bars in grouped layout (px) */
+  barGap?: number
+  /** Additional CSS classes */
+  className?: string
+  /** Chart configuration with colors and labels */
+  config: ChartConfig
+  /** Custom tooltip content (replaces default tooltip) */
+  customTooltip?: ReactElement
+  /** Data array for the chart */
+  data: Record<string, unknown>[]
+  /** Enable horizontal scroll/slider for legend with many items */
+  enableLegendSlider?: boolean
+  /** Grid stroke dash array (e.g., "3 3") */
+  gridDashArray?: string
+  /** X-axis interval type for tick display */
+  intervalType?: BarChartIntervalType
+  /** Layout orientation: vertical (bars go up) or horizontal (bars go right) */
+  layout?: BarChartLayout
+  /** Legend position relative to chart */
+  legendPosition?: BarChartLegendPosition
+  /** Maximum value axis bound (explicit domain upper bound) */
+  maxValue?: number
+  /** Minimum value axis bound (explicit domain lower bound) */
+  minValue?: number
+  /** Callback when a bar is clicked. Pass null to clear selection. */
+  onValueChange?: (value: BarChartEventProps | null) => void
+  /** Border radius for bars */
+  radius?: number
+  /** Array of data keys or series configs for bar values */
+  series: (BarChartSeriesConfig | string)[]
+  /** Show cartesian grid */
+  showGrid?: boolean
+  /** Show legend */
+  showLegend?: boolean
+  /** Show tooltip on hover */
+  showTooltip?: boolean
+  /** Show X-axis */
+  showXAxis?: boolean
+  /** Show Y-axis */
+  showYAxis?: boolean
+  /** Show only first and last category axis tick labels */
+  startEndOnly?: boolean
+  /** Minimum gap between X-axis ticks in pixels */
+  tickGap?: number
+  /** Callback when tooltip state changes */
+  tooltipCallback?: (props: BarChartTooltipCallbackProps) => void
+  /** Tooltip indicator style */
+  tooltipIndicator?: BarChartTooltipIndicator
+  /** Visual variant */
+  variant?: BarChartVariant
+  /** Label for X-axis */
+  xAxisLabel?: string
+  /** Key from data to use for categorical axis (X-axis for vertical, Y-axis for horizontal) */
+  xAxisKey: string
+  /** Custom X-axis tick formatter */
+  xAxisTickFormatter?: (value: unknown) => string
+  /** Label for Y-axis */
+  yAxisLabel?: string
+  /** Custom Y-axis tick formatter */
+  yAxisTickFormatter?: (value: unknown) => string
+  /** Width of the Y-axis in pixels */
+  yAxisWidth?: number
+}

package/src/components/data-display/BarChart/BarChart.variants.ts

@@ -0,0 +1,61 @@
+// BarChart/BarChart.variants.ts
+import { cva, type VariantProps } from "class-variance-authority"
+
+/**
+ * BarChart style variants using CVA
+ *
+ * Controls the bar appearance and layout.
+ *
+ * @see https://cva.style/docs
+ */
+export const barChartVariants = cva(
+  // Base styles (always applied)
+  "",
+  {
+    variants: {
+      layout: {
+        vertical: "",
+        horizontal: "",
+      },
+      stackType: {
+        none: "",
+        stacked: "",
+        percent: "",
+      },
+      barStyle: {
+        default: "",
+        rounded: "",
+      },
+    },
+    defaultVariants: {
+      layout: "vertical",
+      stackType: "none",
+      barStyle: "default",
+    },
+  }
+)
+
+/**
+ * Bar radius configuration
+ */
+export const barRadius = {
+  none: 0,
+  sm: 2,
+  default: 4,
+  lg: 8,
+} as const
+
+/**
+ * Bar gap configuration
+ */
+export const barGap = {
+  tight: 2,
+  default: 4,
+  loose: 8,
+} as const
+
+export type BarRadius = keyof typeof barRadius
+export type BarGap = keyof typeof barGap
+
+// Export variant prop types
+export type BarChartVariantProps = VariantProps<typeof barChartVariants>

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

@@ -0,0 +1,205 @@
+# BarChart
+
+## Visão Geral
+
+O BarChart e um componente de visualizacao de dados que exibe valores categoricos como barras retangulares. A altura ou comprimento das barras e proporcional aos valores que representam. Ideal para comparacoes entre categorias.
+
+### Classificacao Atomica
+- **Categoria**: Organisms
+- **Subcategoria**: Data Display / Charts
+
+### Casos de Uso Comuns
+- Comparacao de vendas por produto
+- Ranking de performance
+- Distribuicao por categoria
+- Votacao e pesquisas
+- Metricas por periodo
+- Comparacao entre equipes/regioes
+
+### Relacao com Outros Componentes
+- **Chart**: Componente base com ChartContainer
+- **LineChart**: Para tendencias temporais
+- **PieChart**: Para proporcoes do todo
+- **ChartLegend**: Legenda para multiplas series
+
+## Design Specs
+
+### Orientacoes
+
+| Orientacao | Layout | Uso |
+|------------|--------|-----|
+| `vertical` | Barras de baixo para cima | Padrao, maioria dos casos |
+| `horizontal` | Barras da esquerda para direita | Labels longos, rankings |
+
+### Variantes
+
+| Variante | Descricao |
+|----------|-----------|
+| `grouped` | Barras lado a lado para comparacao |
+| `stacked` | Barras empilhadas para composicao |
+| `stacked100` | Empilhado 100% para proporcoes |
+
+### Estados
+
+- **Default**: Barras renderizadas
+- **Hover**: Barra destacada com tooltip
+- **Empty**: Mensagem quando sem dados
+
+### Tokens de Design
+
+#### Cores
+- Bar Fill: `var(--color-{series})`
+- Border Radius: `radius={4}`
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `data` | `Array<Record<string, any>>` | - | Dados do grafico |
+| `config` | `ChartConfig` | - | Configuracao de series |
+| `dataKey` | `string` | - | Chave do eixo categorico |
+| `series` | `string[]` | - | Chaves das series de valor |
+| `layout` | `"vertical" \| "horizontal"` | `"vertical"` | Orientacao |
+| `stacked` | `boolean` | `false` | Empilhar barras |
+| `radius` | `number` | `4` | Arredondamento das barras |
+| `barGap` | `number` | `4` | Espaco entre barras |
+| `showGrid` | `boolean` | `true` | Mostrar grid |
+| `showTooltip` | `boolean` | `true` | Mostrar tooltip |
+| `showLegend` | `boolean` | `false` | Mostrar legenda |
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { ChartContainer, ChartTooltip, ChartTooltipContent, type ChartConfig } from '@etus/ui'
+import { Bar, BarChart, XAxis, YAxis, CartesianGrid } 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}>
+        <CartesianGrid strokeDasharray="3 3" vertical={false} />
+        <XAxis dataKey="month" />
+        <YAxis />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
+        <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
+      </BarChart>
+    </ChartContainer>
+  )
+}
+```
+
+### Stacked Bar Chart
+
+```tsx
+function StackedBarChart() {
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <BarChart data={data}>
+        <XAxis dataKey="month" />
+        <YAxis />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <Bar dataKey="desktop" stackId="a" fill="var(--color-desktop)" />
+        <Bar dataKey="mobile" stackId="a" fill="var(--color-mobile)" />
+      </BarChart>
+    </ChartContainer>
+  )
+}
+```
+
+### Horizontal Bar Chart
+
+```tsx
+function HorizontalBarChart() {
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <BarChart data={data} layout="vertical">
+        <XAxis type="number" />
+        <YAxis dataKey="month" type="category" />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
+      </BarChart>
+    </ChartContainer>
+  )
+}
+```
+
+### Com Labels nas Barras
+
+```tsx
+import { LabelList } from 'recharts'
+
+function BarChartWithLabels() {
+  return (
+    <ChartContainer config={chartConfig} className="h-[300px]">
+      <BarChart data={data}>
+        <XAxis dataKey="month" />
+        <YAxis />
+        <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4}>
+          <LabelList dataKey="desktop" position="top" />
+        </Bar>
+      </BarChart>
+    </ChartContainer>
+  )
+}
+```
+
+## Acessibilidade (A11y)
+
+### Recomendacoes
+- Fornecer descricao textual dos dados
+- Usar cores com contraste entre barras
+- Considerar patterns para daltonicos
+- Tabela de dados como alternativa
+
+### ARIA
+- Container com `aria-label` descritivo
+- Dados tabulares para screen readers
+
+## Testes
+
+```typescript
+import { render, screen } from '@testing-library/react'
+import { ChartContainer } from '../Chart'
+import { BarChart, Bar, XAxis, YAxis } from 'recharts'
+
+describe('BarChart', () => {
+  it('renders bars correctly', () => {
+    const data = [{ name: 'A', value: 100 }]
+    const config = { value: { label: 'Value', color: '#000' } }
+
+    render(
+      <ChartContainer config={config}>
+        <BarChart data={data}>
+          <XAxis dataKey="name" />
+          <YAxis />
+          <Bar dataKey="value" />
+        </BarChart>
+      </ChartContainer>
+    )
+
+    expect(screen.getByRole('presentation')).toBeInTheDocument()
+  })
+})
+```
+
+## Referências
+
+- [Recharts BarChart](https://recharts.org/en-US/api/BarChart)
+- [Shadcn UI Charts](https://ui.shadcn.com/docs/components/chart)
+- [Tremor BarChart](https://www.tremor.so/docs/visualizations/bar-chart)