@birhaus/charts

Data visualization components with Spanish-first support for BIRHAUS design system

Professional chart and data visualization components built for Spanish-first applications, following BIRHAUS UX principles for cognitive load reduction.

🚀 Features

• 📊 Professional Charts - Built with D3.js and Recharts for production quality
• 🇪🇸 Spanish-First - All labels, tooltips, and legends in Spanish by default
• ♿ Accessibility - WCAG AA+ compliant with screen reader support
• 📱 Responsive - Mobile-optimized chart layouts
• 🎨 BIRHAUS UX - Cognitive load reduction and progressive disclosure
• 🌙 Dark Mode - Automatic theme adaptation
• 💾 Export Ready - Built-in SVG/PNG export functionality
• 🔢 Data Smart - Automatic number formatting for Spanish locales

📦 Installation

npm install @birhaus/charts

# Peer dependencies
npm install react react-dom @birhaus/tokens @birhaus/primitives

🎯 Quick Start

import { BirhausLineChart, BirhausSparkline, BirhausGradeDistribution } from '@birhaus/charts'

function DashboardCharts() {
  const salesData = [
    { fecha: '2024-01', ventas: 150000, meta: 120000 },
    { fecha: '2024-02', ventas: 180000, meta: 140000 },
    { fecha: '2024-03', ventas: 165000, meta: 160000 },
  ]

  return (
    <div>
      {/* Professional Line Chart */}
      <BirhausLineChart
        data={salesData}
        titleEs="Ventas Mensuales"
        titleEn="Monthly Sales"
        xAxisKey="fecha"
        lines={[
          { key: 'ventas', color: '#3B82F6', name: 'Ventas Reales' },
          { key: 'meta', color: '#10B981', name: 'Meta' }
        ]}
        showTrend={true}
        showExport={true}
      />

      {/* Minimal Trend Indicator */}
      <BirhausSparkline
        data={[120, 135, 148, 162, 158, 171, 180]}
        color="#EF4444"
        showLastValue={true}
        formatValue={(value) => `₲ ${value.toLocaleString()}`}
      />

      {/* Educational Grade Distribution */}
      <BirhausGradeDistribution
        data={gradeData}
        titleEs="Distribución de Notas"
        showPercentages={true}
        colorScheme="academic"
      />
    </div>
  )
}

📋 Components

| Component | Description | Best Used For | |-----------|-------------|---------------| | BirhausLineChart | Multi-line time series charts | Sales trends, financial performance, growth metrics | | BirhausSparkline | Minimal inline trend indicators | KPI cards, dashboard summaries, quick trends | | BirhausGradeDistribution | Educational grade distribution | Academic performance, student analytics | | BirhausKPIDashboard | KPI metric collections | Executive dashboards, performance monitoring |

📊 Line Chart

Basic Usage

import { BirhausLineChart } from '@birhaus/charts'

const data = [
  { mes: 'Enero', ingresos: 500000, gastos: 350000 },
  { mes: 'Febrero', ingresos: 650000, gastos: 400000 },
  { mes: 'Marzo', ingresos: 750000, gastos: 450000 },
]

<BirhausLineChart
  data={data}
  titleEs="Flujo de Caja Mensual"
  titleEn="Monthly Cash Flow"
  xAxisKey="mes"
  lines={[
    { 
      key: 'ingresos', 
      color: '#10B981', 
      name: 'Ingresos',
      strokeWidth: 3
    },
    { 
      key: 'gastos', 
      color: '#EF4444', 
      name: 'Gastos',
      strokeDasharray: '5,5' // Dashed line
    }
  ]}
  height={400}
  showGrid={true}
  showLegend={true}
  showTooltip={true}
/>

Advanced Features

<BirhausLineChart
  data={financialData}
  titleEs="Rendimiento de Inversiones"
  subtitle="Comparación anual 2023-2024"
  xAxisKey="fecha"
  lines={[
    { key: 'portfolio', color: '#3B82F6', name: 'Portafolio' },
    { key: 'benchmark', color: '#8B5CF6', name: 'Índice de Referencia' }
  ]}
  
  // Spanish-first formatting
  formatXAxis={(value) => new Date(value).toLocaleDateString('es-PY')}
  formatYAxis={(value) => `₲ ${value.toLocaleString('es-PY')}`}
  formatTooltip={(value, name) => [`₲ ${value.toLocaleString('es-PY')}`, name]}
  
  // Export functionality
  showExport={true}
  exportFormats={['png', 'svg', 'csv']}
  
  // Trend analysis
  showTrend={true}
  trendColor="#10B981"
  
  // Cognitive load reduction
  maxDataPoints={12} // Limit data points for clarity
  animationDuration={750}
/>

⚡ Sparkline

Minimal trend indicators perfect for KPI cards and dashboard summaries:

import { BirhausSparkline } from '@birhaus/charts'

// Basic trend
<BirhausSparkline
  data={[10, 15, 12, 18, 22, 19, 25]}
  color="#3B82F6"
  height={40}
  showLastValue={true}
/>

// Financial sparkline
<BirhausSparkline
  data={monthlyRevenue}
  color="#10B981"
  showLastValue={true}
  formatValue={(value) => `₲ ${(value / 1000).toFixed(0)}K`}
  showTrend={true}
  strokeWidth={2}
/>

// Comparison sparklines
<div className="grid grid-cols-3 gap-4">
  <div>
    <p>Ventas</p>
    <BirhausSparkline data={salesData} color="#3B82F6" />
  </div>
  <div>
    <p>Costos</p>
    <BirhausSparkline data={costData} color="#EF4444" />
  </div>
  <div>
    <p>Ganancia</p>
    <BirhausSparkline data={profitData} color="#10B981" />
  </div>
</div>

🎓 Grade Distribution

Perfect for educational institutions and student performance tracking:

import { BirhausGradeDistribution } from '@birhaus/charts'

const gradeData = [
  { grade: 'A', count: 15, label: 'Excelente' },
  { grade: 'B', count: 25, label: 'Bueno' },
  { grade: 'C', count: 30, label: 'Regular' },
  { grade: 'D', count: 12, label: 'Insuficiente' },
  { grade: 'F', count: 3, label: 'Reprobado' }
]

<BirhausGradeDistribution
  data={gradeData}
  titleEs="Distribución de Calificaciones - Matemática I"
  titleEn="Grade Distribution - Mathematics I"
  showPercentages={true}
  showStudentCount={true}
  colorScheme="academic" // Green to red gradient
  height={300}
  
  // Spanish-first labels
  tooltipFormatter={(entry) => [
    `${entry.count} estudiantes (${entry.percentage}%)`,
    entry.label
  ]}
/>

📈 KPI Dashboard

Comprehensive KPI visualization with multiple chart types:

import { BirhausKPIDashboard } from '@birhaus/charts'

const kpiData = {
  revenue: {
    current: 1500000,
    previous: 1200000,
    target: 1800000,
    trend: [100, 120, 135, 140, 150]
  },
  students: {
    current: 450,
    previous: 425,
    target: 500,
    trend: [400, 415, 430, 445, 450]
  },
  satisfaction: {
    current: 4.2,
    previous: 4.0,
    target: 4.5,
    trend: [3.8, 3.9, 4.0, 4.1, 4.2]
  }
}

<BirhausKPIDashboard
  data={kpiData}
  titleEs="Panel de Control Ejecutivo"
  layout="grid" // or 'row'
  showTrends={true}
  showTargets={true}
  period="monthly"
  
  // Spanish-first KPI labels
  labels={{
    revenue: { es: 'Ingresos', en: 'Revenue' },
    students: { es: 'Estudiantes', en: 'Students' },
    satisfaction: { es: 'Satisfacción', en: 'Satisfaction' }
  }}
  
  // Custom formatters
  formatters={{
    revenue: (value) => `₲ ${(value / 1000).toFixed(0)}K`,
    students: (value) => `${value} estudiantes`,
    satisfaction: (value) => `${value}/5 ⭐`
  }}
/>

🎨 BIRHAUS UX Principles

Cognitive Load Reduction

// ❌ Cognitive overload - too much information
<ComplexChart data={data} showAllMetrics={true} />

// ✅ BIRHAUS approach - progressive disclosure
<BirhausLineChart
  data={data}
  maxDataPoints={7} // Miller's Law - 7±2 items
  progressiveDisclosure={true} // Click to reveal more detail
  primaryMetric="ingresos" // Focus on one key metric
  
  // Secondary metrics revealed on hover/click
  secondaryMetrics={['gastos', 'ganancia']}
/>

Spanish-First Design

// All components default to Spanish
<BirhausLineChart
  titleEs="Ventas por Trimestre" // Primary
  titleEn="Quarterly Sales"      // Fallback
  data={data}
  
  // Spanish number formatting
  formatYAxis={(value) => `₲ ${value.toLocaleString('es-PY')}`}
  
  // Spanish month names
  formatXAxis={(value) => new Date(value).toLocaleDateString('es-PY', { 
    month: 'long', 
    year: 'numeric' 
  })}
/>

Accessibility Features

All charts include:

• Screen Reader Support - Proper ARIA labels and data tables
• Keyboard Navigation - Tab through data points and controls
• High Contrast Mode - Automatic color adjustments
• Focus Indicators - Clear visual focus states
• Alternative Text - Descriptive alt text for exported images

🌙 Dark Mode Support

Charts automatically adapt to your theme:

import { BirhausProvider } from '@birhaus/provider'

<BirhausProvider theme="dark">
  <BirhausLineChart
    data={data}
    // Automatically uses dark theme colors
    // Text and gridlines adapt
    // Export maintains theme consistency
  />
</BirhausProvider>

💾 Export Functionality

Built-in export options for all chart types:

<BirhausLineChart
  data={data}
  showExport={true}
  exportFormats={['png', 'svg', 'csv', 'pdf']}
  exportFilename="ventas-mensuales-2024"
  
  // Custom export options
  exportOptions={{
    png: { width: 1200, height: 600, scale: 2 },
    svg: { preserveFonts: true },
    csv: { includeHeaders: true, delimiter: ';' },
    pdf: { orientation: 'landscape', title: 'Reporte de Ventas' }
  }}
/>

📱 Responsive Design

Charts automatically adapt to different screen sizes:

<BirhausLineChart
  data={data}
  responsive={true}
  
  // Desktop: Full chart with legend
  // Tablet: Simplified legend
  // Mobile: Hide legend, show tooltip on tap
  
  breakpoints={{
    mobile: 640,
    tablet: 1024
  }}
  
  mobileOptimizations={{
    hideXAxisLabels: true,
    simplifyTooltip: true,
    increaseTooltipSize: true
  }}
/>

🔧 Customization

Custom Color Schemes

const customTheme = {
  primary: '#1F6FEB',
  secondary: '#10B981',
  accent: '#F59E0B',
  danger: '#EF4444',
  success: '#10B981',
  warning: '#F59E0B'
}

<BirhausLineChart
  data={data}
  colorScheme={customTheme}
  // OR use predefined schemes
  colorScheme="financial" // Blue/green for money
  colorScheme="academic"  // Green/red for grades
  colorScheme="health"    // Soft pastels
/>

Custom Animations

<BirhausLineChart
  data={data}
  animation={{
    duration: 1000,
    easing: 'ease-out',
    delay: 200,
    stagger: 100 // Stagger line animations
  }}
  
  // Hover animations
  hoverEffects={{
    scale: 1.1,
    shadowBlur: 10,
    duration: 200
  }}
/>

🧪 Testing

Testing utilities for chart components:

import { render, screen } from '@testing-library/react'
import { BirhausLineChart } from '@birhaus/charts'
import { axe, toHaveNoViolations } from 'jest-axe'

expect.extend(toHaveNoViolations)

test('BirhausLineChart accessibility', async () => {
  const { container } = render(
    <BirhausLineChart data={mockData} titleEs="Test Chart" />
  )
  
  // Check for accessibility violations
  const results = await axe(container)
  expect(results).toHaveNoViolations()
  
  // Check ARIA labels
  expect(screen.getByLabelText('Test Chart')).toBeInTheDocument()
})

🚀 Performance

• Bundle Size: ~45KB gzipped (including D3 utilities)
• Render Performance: Optimized for 60fps animations
• Memory Usage: Efficient data structures, automatic cleanup
• Large Datasets: Virtual scrolling for 10,000+ data points

📚 Examples

Financial Dashboard

function FinancialDashboard() {
  return (
    <div className="space-y-6">
      {/* Revenue Trend */}
      <BirhausLineChart
        data={revenueData}
        titleEs="Ingresos Mensuales"
        lines={[{ key: 'ingresos', color: '#10B981', name: 'Ingresos' }]}
        showTrend={true}
      />
      
      {/* Quick KPIs */}
      <div className="grid grid-cols-4 gap-4">
        <div className="p-4 bg-white rounded-lg">
          <h3>Ventas Hoy</h3>
          <BirhausSparkline data={todaySales} color="#3B82F6" />
        </div>
        {/* More KPI cards... */}
      </div>
    </div>
  )
}

Educational Analytics

function StudentAnalytics() {
  return (
    <div>
      <BirhausGradeDistribution
        data={semesterGrades}
        titleEs="Rendimiento Académico - Semestre I"
        showPercentages={true}
        colorScheme="academic"
      />
    </div>
  )
}

🐛 Troubleshooting

Common Issues

Charts not rendering

// Ensure data is properly formatted
const data = [
  { x: 'Jan', y: 100 }, // ✅ Correct
  { x: null, y: 200 },  // ❌ Null values cause issues
]

// Filter out null values
const cleanData = data.filter(d => d.x !== null && d.y !== null)

TypeScript errors

npm install @types/d3 --save-dev

Spanish formatting issues

// Ensure locale is set properly
import { BirhausProvider } from '@birhaus/provider'

<BirhausProvider locale="es-PY">
  <YourCharts />
</BirhausProvider>

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

📄 License

MIT © BIRHAUS Team

Visualiza datos con estilo español y simplicidad BIRHAUS 📊🇪🇸