Saar-chart NPM

SaarChart

SaarChart is a versatile, responsive, and feature-rich React chart component built on top of Chart.js and react-chartjs-2. It supports multiple chart types, theming, accessibility features, and advanced customization options, making it easy to integrate into any React application.

Features
Installation
Usage
- Basic Example
- Advanced Example
Props
Advanced Features
Theming Support
Accessibility
Component Implementation
Development
Contributing
License

Features

Multiple Chart Types: Supports Bar, Pie, Line, Doughnut, Radar, Polar Area, and more.
Responsive Design: Automatically adjusts to fit the container size.
Customizable: Pass custom data, labels, legends, colors, and options.
Advanced UI/UX: Includes loading states, error handling, interactive tooltips, and animations.
Export Options: Allows exporting charts as images.
Theming Support: Adapts to light or dark themes.
Accessibility: Screen reader friendly and keyboard accessible.

Installation

Prerequisites

Node.js: Ensure you have Node.js installed (preferably the latest LTS version).
NPM: Comes bundled with Node.js.

Installing the Package

Install the package via NPM:

npm install saar-chart

Or via Yarn:

yarn add saar-chart

Peer Dependencies

Ensure that react, react-dom, and chart.js are also installed as peer dependencies. You can add them via:

npm install react react-dom chart.js

Usage

Basic Example

Here's a simple example of how to use the SaarChart component in your application:

import React from 'react';
import SaarChart from 'saar-chart';

const data = {
  labels: ['January', 'February', 'March', 'April', 'May'],
  datasets: [
    {
      label: 'Sales',
      data: [150, 200, 100, 250, 300],
      backgroundColor: 'rgba(75, 192, 192, 0.2)',
      borderColor: 'rgba(75, 192, 192, 1)',
      borderWidth: 1,
    },
  ],
};

const options = {
  responsive: true,
  plugins: {
    legend: {
      position: 'top',
    },
    title: {
      display: true,
      text: 'Monthly Sales Data',
    },
  },
};

const BasicChart = () => {
  return <SaarChart type="bar" data={data} options={options} />;
};

export default BasicChart;

Advanced Example

For more customization, you can pass additional props and make use of event handlers:

import React from 'react';
import SaarChart from 'saar-chart';

const advancedData = {
  labels: ['Red', 'Blue', 'Yellow', 'Green', 'Purple', 'Orange'],
  datasets: [
    {
      label: '# of Votes',
      data: [12, 19, 3, 5, 2, 3],
      backgroundColor: [
        'rgba(255, 99, 132, 0.2)',
        'rgba(54, 162, 235, 0.2)',
        'rgba(255, 206, 86, 0.2)',
        'rgba(75, 192, 192, 0.2)',
        'rgba(153, 102, 255, 0.2)',
        'rgba(255, 159, 64, 0.2)',
      ],
      borderColor: [
        'rgba(255, 99, 132, 1)',
        'rgba(54, 162, 235, 1)',
        'rgba(255, 206, 86, 1)',
        'rgba(75, 192, 192, 1)',
        'rgba(153, 102, 255, 1)',
        'rgba(255, 159, 64, 1)',
      ],
      borderWidth: 1,
    },
  ],
};

const AdvancedChart = () => {
  const handleClick = (event, chartElement) => {
    if (chartElement.length > 0) {
      console.log('Clicked:', chartElement[0].index);
    }
  };

  return (
    <SaarChart
      type="doughnut"
      data={advancedData}
      options={{
        onClick: handleClick,
        plugins: {
          legend: {
            position: 'right',
          },
        },
      }}
    />
  );
};

export default AdvancedChart;

Props

type (string): Type of the chart (e.g., 'bar', 'line', 'pie').
data (object): Data for the chart.
options (object): Chart.js configuration options.
height (number): Height of the canvas element.
width (number): Width of the canvas element.
onClick (function): Event handler for chart click events.

Advanced Features

Loading State: Use loading prop to display a loading spinner while the chart is being loaded.
Error Handling: The error prop can display a fallback UI in case of any issues.
Animation: You can control chart animations through the options.animation parameter.

Theming Support

The SaarChart component supports theming for light and dark modes. You can pass a theme prop (light or dark) to adjust the chart styles accordingly:

<SaarChart type="bar" data={data} options={options} theme="dark" />

Accessibility

ARIA Support: The charts include relevant ARIA labels to enhance accessibility.
Keyboard Navigation: The component is built to be navigable via keyboard shortcuts.

Component Implementation

The SaarChart is implemented as a wrapper around the popular react-chartjs-2 library, which is itself a React wrapper for Chart.js. This provides full access to Chart.js features while maintaining React component conventions for state and props management.

Development

Project Structure

src/: Contains the main code for the SaarChart component.
examples/: Sample applications demonstrating how to use SaarChart.
tests/: Contains unit and integration tests for ensuring component quality.

Building the Package

To build the package for production, run:

npm run build

This will create a dist folder with the compiled JavaScript files ready to be published.

Troubleshooting

Chart Not Displaying: Make sure you have included all peer dependencies (react, chart.js).
Incorrect Data Display: Verify that the data structure matches Chart.js expectations.
Console Warnings: Ensure all required props are passed correctly to the component.