@pol-studios/charts

Chart components for POL applications

A comprehensive charting library built on top of Recharts. Provides ready-to-use chart components (Pie, Bar, Line, Area, Combo, Gauge, Heatmap), chart cards, skeleton loaders, and a generator system for dynamic chart creation.

Installation

pnpm add @pol-studios/charts

Peer Dependencies

pnpm add react react-dom recharts @heroui/react @heroicons/react @pol-studios/hooks @pol-studios/ui @pol-studios/utils

Quick Start

import { PieChart, BarChart, LineChart } from "@pol-studios/charts";

// Simple pie chart
function StatusBreakdown({ data }) {
  return (
    <PieChart
      data={data}
      dataKey="value"
      nameKey="name"
      title="Status Distribution"
    />
  );
}

// Bar chart with multiple series
function MonthlySales({ data }) {
  return (
    <BarChart
      data={data}
      xAxisKey="month"
      series={[
        { dataKey: "sales", name: "Sales", color: "#3b82f6" },
        { dataKey: "returns", name: "Returns", color: "#ef4444" },
      ]}
    />
  );
}

// Line chart with area fill
function TrendChart({ data }) {
  return (
    <LineChart
      data={data}
      xAxisKey="date"
      series={[{ dataKey: "value", name: "Trend" }]}
      showArea
    />
  );
}

Subpath Exports

| Path | Description | |------|-------------| | @pol-studios/charts | All exports combined | | @pol-studios/charts/recharts | Core chart components | | @pol-studios/charts/cards | Chart card wrappers | | @pol-studios/charts/generator | Dynamic chart generation system | | @pol-studios/charts/skeletons | Loading skeleton components | | @pol-studios/charts/hooks | Chart-related hooks | | @pol-studios/charts/utils | Data transformation utilities |

API Reference

Chart Components

import {
  PieChart,
  BarChart,
  LineChart,
  AreaChart,
  ComboChart,
  GaugeChart,
  HeatmapChart,
} from "@pol-studios/charts";

// Pie Chart
<PieChart
  data={[{ name: "A", value: 30 }, { name: "B", value: 70 }]}
  dataKey="value"
  nameKey="name"
  title="Distribution"
  showLegend
  showLabels
/>

// Bar Chart
<BarChart
  data={data}
  xAxisKey="category"
  series={[{ dataKey: "value", name: "Value", color: "#3b82f6" }]}
  stacked={false}
  horizontal={false}
/>

// Line Chart
<LineChart
  data={data}
  xAxisKey="date"
  series={[{ dataKey: "value", name: "Trend" }]}
  showDots
  curved
/>

// Area Chart
<AreaChart
  data={data}
  xAxisKey="date"
  series={[{ dataKey: "value", name: "Volume" }]}
  stacked
  gradient
/>

// Combo Chart (mixed bar + line)
<ComboChart
  data={data}
  xAxisKey="month"
  barSeries={[{ dataKey: "sales", name: "Sales" }]}
  lineSeries={[{ dataKey: "trend", name: "Trend" }]}
/>

// Gauge Chart
<GaugeChart
  value={75}
  max={100}
  title="Completion"
  colors={["#ef4444", "#f59e0b", "#22c55e"]}
/>

// Heatmap Chart
<HeatmapChart
  data={data}
  xAxisKey="day"
  yAxisKey="hour"
  valueKey="count"
/>

Backward Compatibility

For migration from previous versions, legacy names are supported:

// Recharts* prefix (v2 naming)
import { RechartsPieChart, RechartsBarChart } from "@pol-studios/charts";

// ECharts* prefix (v1 naming, deprecated)
import { EChartsPieChart, EChartsBarChart } from "@pol-studios/charts";

Chart Cards

import {
  BaseChartCard,
  CircleChartCard,
  ChartWithHoverButtons,
  SummaryCards,
} from "@pol-studios/charts/cards";

// Base card wrapper
<BaseChartCard title="Sales Overview" subtitle="Last 30 days">
  <BarChart data={data} ... />
</BaseChartCard>

// Circle chart with navigation
<CircleChartCard
  data={data}
  title="Status"
  onNavigate={(item) => router.push(`/items/${item.id}`)}
/>

// Chart with hover action buttons
<ChartWithHoverButtons
  chart={<PieChart data={data} ... />}
  actions={[
    { icon: <ExpandIcon />, onClick: handleExpand },
    { icon: <ExportIcon />, onClick: handleExport },
  ]}
/>

// Summary statistics cards
<SummaryCards
  items={[
    { label: "Total", value: 1234, change: 5.2 },
    { label: "Active", value: 890, change: -2.1 },
  ]}
/>

Chart Generator

import {
  ChartGenerator,
  ChartGridView,
  ChartRenderer,
  ChartSidebar,
  StatsView,
  TabNavigation,
  ListViewModal,
  MobileMenuModal,
  VisualizerSkeleton,
} from "@pol-studios/charts/generator";

// Dynamic chart generation from configuration
<ChartGenerator
  config={chartConfig}
  data={data}
  onConfigChange={handleConfigChange}
/>

// Grid of multiple charts
<ChartGridView
  charts={chartConfigs}
  data={dataMap}
  columns={3}
/>

// Render chart from config
<ChartRenderer
  type="bar"
  config={config}
  data={data}
/>

// Configuration sidebar
<ChartSidebar
  config={config}
  onChange={handleChange}
  availableFields={fields}
/>

Skeleton Loaders

import {
  PieSkeleton,
  BarSkeleton,
  LineSkeleton,
  GaugeSkeleton,
  HeatmapSkeleton,
  ChartSkeleton,
} from "@pol-studios/charts/skeletons";

// Type-specific skeletons
<PieSkeleton />
<BarSkeleton />
<LineSkeleton />

// Factory function for dynamic type
<ChartSkeleton type="pie" />
<ChartSkeleton type="bar" />

Hooks

import { useChartTheme } from "@pol-studios/charts/hooks";

// Get theme-aware chart colors
const { colors, textColor, gridColor } = useChartTheme();

Utilities

import { transformData, aggregateBy } from "@pol-studios/charts/utils";

// Data transformation utilities for chart formatting

TypeScript Types

import type {
  // Generator types
  ChartConfig,
  ChartType,
  SeriesConfig,
  AxisConfig,

  // Navigation types
  NavigateOptions,
} from "@pol-studios/charts";

Related Packages

• @pol-studios/ui - UI components (required peer dependency)
• @pol-studios/hooks - React hooks (required peer dependency)
• @pol-studios/utils - Utility functions (required peer dependency)

License

UNLICENSED