analytics-suman

A simple yet powerful data visualization library for React and Next.js applications. This library intelligently transforms arrays and objects into visually appealing analytics components with minimal configuration.

Features

• Smart Chart Detection: Automatically determines the best chart type based on your data structure
• Multiple Chart Types: Bar charts, line charts, pie/donut charts, and data tables
• Responsive Design: All charts automatically adapt to container size
• Custom Theming: Several built-in color themes with the ability to customize
• Time Series Support: Automatically detects and properly formats time-series data
• Interactive Elements: Sorting, pagination, and search functionality for data tables
• Zero Dependencies: Lightweight with no external dependencies, just React

Installation

npm install analytics-suman
# or
yarn add analytics-suman

Quick Start

import React from "react";
import { SmartChart } from "analytics-suman";

const MyAnalytics = () => {
  // Sample data - can be array of objects, simple array, or object
  const data = [
    { month: "January", sales: 65, expenses: 50 },
    { month: "February", sales: 59, expenses: 45 },
    { month: "March", sales: 80, expenses: 60 },
    { month: "April", sales: 81, expenses: 55 },
    { month: "May", sales: 56, expenses: 48 },
    { month: "June", sales: 55, expenses: 52 },
  ];

  return (
    <div>
      <h1>Sales Analytics</h1>

      {/* SmartChart automatically chooses the best visualization */}
      <SmartChart
        data={data}
        title="Monthly Sales Performance"
        options={{ showControls: true }}
      />
    </div>
  );
};

export default MyAnalytics;

Components

SmartChart

The main component that intelligently selects the best visualization for your data.

import { SmartChart, THEMES } from "analytics-suman";

// Usage
<SmartChart
  data={yourData}
  title="Chart Title"
  height={400}
  theme={THEMES.VIBRANT}
  options={{
    showControls: true, // Allow user to switch chart types
    showInfo: true, // Show detected chart type
    // Other chart-specific options
  }}
/>;

Specific Chart Types

If you want to use a specific chart type, you can import it directly:

import { BarChart, LineChart, PieChart, DataTable } from 'analytics-suman';

// Bar Chart
<BarChart
  data={data}
  xKey="category"
  yKey="value"
  title="Bar Chart Example"
  horizontal={false}
/>

// Line Chart
<LineChart
  data={data}
  xKey="date"
  yKey="value"
  showArea={true}
  timeScale={true}
/>

// Pie Chart
<PieChart
  data={data}
  labelKey="category"
  valueKey="percentage"
  donut={true}
/>

// Data Table
<DataTable
  data={data}
  searchable={true}
  sortable={true}
  pagination={true}
/>

Data Format

The library accepts various data formats:

Array of Objects (most common)

const data = [
  { category: "A", value: 10, otherValue: 20 },
  { category: "B", value: 15, otherValue: 25 },
  // ...
];

Simple Arrays

// Numeric array (will be visualized as bar chart)
const data = [10, 20, 30, 40, 50];

// String array (will be visualized as pie chart)
const data = ["A", "B", "C", "D"];

Object (key-value pairs)

// Will be visualized as pie or bar chart
const data = {
  "Category A": 10,
  "Category B": 20,
  "Category C": 30,
};

Customization

Themes

The library includes several built-in color themes:

import { SmartChart, THEMES } from "analytics-suman";

// Available themes:
// - THEMES.DEFAULT
// - THEMES.DARK
// - THEMES.PASTEL
// - THEMES.VIBRANT
// - THEMES.MONOCHROME

<SmartChart data={data} theme={THEMES.VIBRANT} />;

Chart Options

Each chart type supports various options:

Bar Chart Options

<BarChart
  horizontal={true} // Horizontal or vertical bars
  showValues={true} // Show values above bars
  animation={true} // Animate on load/update
/>

Line Chart Options

<LineChart
  showPoints={true} // Show data points
  showArea={true} // Show area under the line
  curveSmooth={true} // Use curved lines
  gridLines={true} // Show grid lines
  timeScale={true} // Format X-axis as time
/>

Pie Chart Options

<PieChart
  donut={true} // Donut chart style
  showLabels={true} // Show labels on slices
  showValues={true} // Show values/percentages
  showLegend={true} // Show legend
/>

Data Table Options

<DataTable
  bordered={true} // Show borders
  striped={true} // Striped rows
  searchable={true} // Enable search
  sortable={true} // Enable sorting
  pagination={true} // Enable pagination
  pageSize={10} // Items per page
/>

Advanced Usage

Custom Column Definitions

For DataTable, you can define custom columns:

const columns = [
  { key: "id", label: "ID", sortable: true },
  {
    key: "amount",
    label: "Amount ($)",
    sortable: true,
    format: (value) => `$${value.toFixed(2)}`, // Custom formatter
  },
  { key: "date", label: "Transaction Date" },
];

<DataTable data={data} columns={columns} />;

Utility Functions

The library exports several utility functions for data processing:

import {
  detectChartType,
  normalizeData,
  aggregateData,
  formatTimeSeries,
} from "analytics-suman";

// Detect the best chart type for your data
const chartType = detectChartType(myData);

// Normalize data to consistent format
const normalized = normalizeData(myData);

// Aggregate data for pie/bar charts
const aggregated = aggregateData(data, "category", "value");

// Format time series data
const timeSeriesData = formatTimeSeries(data, "date", "value");

Examples

Dashboard with Multiple Charts

import React from "react";
import { SmartChart, BarChart, PieChart, THEMES } from "analytics-suman";

const Dashboard = () => {
  const salesData = [
    { month: "Jan", value: 1200 },
    { month: "Feb", value: 1900 },
    { month: "Mar", value: 1500 },
    { month: "Apr", value: 2200 },
    { month: "May", value: 2500 },
    { month: "Jun", value: 2100 },
  ];

  const categoryData = {
    Electronics: 35,
    Clothing: 20,
    "Home & Kitchen": 15,
    Books: 10,
    Other: 20,
  };

  const customerData = [
    { date: "2023-01-01", newUsers: 120, returningUsers: 250 },
    { date: "2023-02-01", newUsers: 150, returningUsers: 280 },
    { date: "2023-03-01", newUsers: 200, returningUsers: 320 },
    { date: "2023-04-01", newUsers: 250, returningUsers: 350 },
    { date: "2023-05-01", newUsers: 300, returningUsers: 380 },
  ];

  return (
    <div className="dashboard">
      <h1>Sales Dashboard</h1>

      <div style={{ display: "flex", flexWrap: "wrap" }}>
        <div style={{ width: "50%", padding: "10px" }}>
          <BarChart
            data={salesData}
            title="Monthly Sales"
            theme={THEMES.DEFAULT}
          />
        </div>

        <div style={{ width: "50%", padding: "10px" }}>
          <PieChart
            data={categoryData}
            title="Sales by Category"
            theme={THEMES.VIBRANT}
            donut={true}
          />
        </div>

        <div style={{ width: "100%", padding: "10px" }}>
          <SmartChart
            data={customerData}
            title="Customer Growth"
            options={{
              timeScale: true,
              showArea: true,
              xKey: "date",
              showControls: true,
            }}
            theme={THEMES.PASTEL}
          />
        </div>
      </div>
    </div>
  );
};

export default Dashboard;

Real-time Data

import React, { useState, useEffect } from "react";
import { LineChart } from "analytics-suman";

const RealTimeChart = () => {
  const [data, setData] = useState([]);

  useEffect(() => {
    // Initial data
    const initialData = Array.from({ length: 20 }).map((_, i) => ({
      time: new Date(Date.now() - (20 - i) * 1000),
      value: Math.random() * 100,
    }));

    setData(initialData);

    // Update every second
    const interval = setInterval(() => {
      setData((currentData) => [
        ...currentData.slice(1),
        {
          time: new Date(),
          value: Math.random() * 100,
        },
      ]);
    }, 1000);

    return () => clearInterval(interval);
  }, []);

  return (
    <LineChart
      data={data}
      xKey="time"
      yKey="value"
      title="Real-time Metrics"
      timeScale={true}
      showPoints={false}
      showArea={true}
    />
  );
};

export default RealTimeChart;

Interactive Dashboard

import React, { useState } from "react";
import { SmartChart, THEMES } from "analytics-suman";

const InteractiveDashboard = () => {
  const [selectedTheme, setSelectedTheme] = useState(THEMES.DEFAULT);
  const [selectedPeriod, setSelectedPeriod] = useState("monthly");

  // Sample data
  const monthlyData = [
    { period: "Jan", sales: 1200, profit: 300 },
    { period: "Feb", sales: 1900, profit: 450 },
    { period: "Mar", sales: 1500, profit: 375 },
    { period: "Apr", sales: 2200, profit: 550 },
    { period: "May", sales: 2500, profit: 625 },
  ];

  const quarterlyData = [
    { period: "Q1", sales: 4600, profit: 1125 },
    { period: "Q2", sales: 5200, profit: 1300 },
    { period: "Q3", sales: 6100, profit: 1525 },
    { period: "Q4", sales: 7000, profit: 1750 },
  ];

  const data = selectedPeriod === "monthly" ? monthlyData : quarterlyData;

  return (
    <div>
      <div
        style={{
          display: "flex",
          justifyContent: "space-between",
          marginBottom: "20px",
        }}
      >
        <div>
          <label htmlFor="period-select">Time Period: </label>
          <select
            id="period-select"
            value={selectedPeriod}
            onChange={(e) => setSelectedPeriod(e.target.value)}
          >
            <option value="monthly">Monthly</option>
            <option value="quarterly">Quarterly</option>
          </select>
        </div>

        <div>
          <label htmlFor="theme-select">Theme: </label>
          <select
            id="theme-select"
            value={selectedTheme}
            onChange={(e) => setSelectedTheme(e.target.value)}
          >
            <option value={THEMES.DEFAULT}>Default</option>
            <option value={THEMES.DARK}>Dark</option>
            <option value={THEMES.PASTEL}>Pastel</option>
            <option value={THEMES.VIBRANT}>Vibrant</option>
            <option value={THEMES.MONOCHROME}>Monochrome</option>
          </select>
        </div>
      </div>

      <SmartChart
        data={data}
        title={`${
          selectedPeriod === "monthly" ? "Monthly" : "Quarterly"
        } Performance`}
        theme={selectedTheme}
        options={{
          showControls: true,
          xKey: "period",
          yKey: "sales",
        }}
      />
    </div>
  );
};

export default InteractiveDashboard;

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT