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.

Table of Contents

• Features
• Installation
  • Prerequisites
  • Installing the Package
  • Peer Dependencies
• Usage
  • Basic Example
  • Advanced Example
• Props
• Advanced Features
• Theming Support
• Accessibility
• Component Implementation
• Development
  • Project Structure
  • Building the Package
  • Troubleshooting
• 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.

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

License

This project is licensed under the MIT License. See the LICENSE file for more information.