@atulya_26/charting-library

A Figma-aligned React charting library for product dashboards, analytics cards, and healthcare-style reporting experiences.

The package is built around reusable chart primitives, polished Storybook props, MDS-compatible chrome, accessibility hooks, performance guardrails, and realistic chart states for loading, empty, and error cases.

Live demo: atulya26.github.io/ChartingLibrary

Live Storybook

Explore the charts without installing the package:

Open the live Storybook

The live Storybook is deployed from the main branch through GitHub Pages, so merged chart and documentation updates become shareable from the repository.

Install

npm install @atulya_26/charting-library

Peer dependencies:

npm install react react-dom

Import the package CSS once in your app entry point:

import '@atulya_26/charting-library/styles.css';

Then import charts as needed:

import { BarChart, DonutChart, LineChart } from '@atulya_26/charting-library';

Available Charts

The library currently includes 10 chart/data-display components:

• BarChart: grouped, stacked, horizontal, and distribution-style bar charts.
• ComboChart: bar plus line overlays for mixed metric views.
• LineChart: single-axis and dual-axis trend charts.
• DonutChart: full donut charts with labels, legends, rounded caps, and fill styles.
• HalfDonutChart: gauge-style half donut progress charts.
• HistogramChart: distribution bins with optional overlay support.
• Sparkline: compact KPI trend lines.
• PointerScale: segmented risk/score scale with a pointer and optional target.
• MapBubbleChart: US/state map bubble views and table fallback.
• SankeyChart: flow charts with configurable node/link behavior.

Supporting state components:

• ChartLoadingSkeleton: chart-aware loading skeletons for each chart type.
• ChartStateCard: empty and error states using chart-card chrome.

Supporting building blocks:

• ChartCard, ChartHeader, ChartShell, ChartToolbar
• Legend, LegendMarker, TooltipPopover, ChartHoverCard
• XAxis, YAxis, GridLines, BarMark, DonutRing, LineSeries

Quick Example

import '@atulya_26/charting-library/styles.css';
import { BarChart, chartTokens } from '@atulya_26/charting-library';

export function RevenueByPayer() {
  return (
    <BarChart
      title="Revenue generated by type of payer"
      categories={['Commercial', 'Medicaid', 'Medicare']}
      yAxis={{ title: '% of total revenue generated', ticks: [0, 25, 50, 75, 100] }}
      series={[
        {
          key: 'generated',
          label: 'Revenue generated',
          fill: chartTokens.categorical.primary,
          data: [45, 40, 20]
        },
        {
          key: 'targeted',
          label: 'Revenue targeted',
          fill: chartTokens.neutral.surfaceTint,
          data: [70, 65, 30]
        }
      ]}
      showHoverCard
    />
  );
}

Data Input

Chart components receive typed JavaScript props. This keeps the core API predictable whether your data comes from an API, CSV, JSON, or a local mock.

CSV can still be used, but it should be parsed and transformed before passing data into the chart:

payer,revenue_generated,revenue_targeted
Commercial,45,70
Medicaid,40,65
Medicare,20,30

const categories = rows.map((row) => row.payer);

const series = [
  {
    key: 'generated',
    label: 'Revenue generated',
    data: rows.map((row) => Number(row.revenue_generated))
  },
  {
    key: 'targeted',
    label: 'Revenue targeted',
    data: rows.map((row) => Number(row.revenue_targeted))
  }
];

This adapter-style approach keeps CSV parsing outside the chart renderer and makes the same chart usable with backend API responses.

Accessibility

Every chart graphic includes a generated accessible title and description. You can override them when product language needs to be more specific:

<LineChart
  title="Average PMPM Trend"
  ariaLabel="Average PMPM trend over four quarters"
  ariaDescription="Line chart showing current PMPM, projected PMPM, and target values."
  categories={['Q1', 'Q2', 'Q3', 'Q4']}
  series={series}
/>

Keyboard inspection is intentionally opt-in so existing chart visuals and tab order do not change by default. Enable it per chart when you want keyboard users to inspect marks, segments, bubbles, and nodes:

<BarChart
  enableKeyboardNavigation
  title="Revenue by payer"
  categories={categories}
  series={series}
/>

Keyboard behavior:

| Key | Action | | ---------------------------- | -------------------------------------------------------------------------- | | Tab | Focus the chart, then leave naturally on the next tab stop | | Arrow Left / Arrow Right | Move to the previous or next data item | | Arrow Up / Arrow Down | Move across series in multi-series charts; otherwise previous or next item | | Home / End | Jump to the first or last item in the current series | | Enter / Space | Trigger the chart item click callback when one exists | | Escape | Clear keyboard focus state and dismiss the hover card |

Focused chart items reuse the same hover-card behavior and visual treatment as pointer hover. The library also honors prefers-reduced-motion for chart loading and hover transitions.

The default palette and text tokens have been audited for the current chart backgrounds. If you pass custom colors, keep text at WCAG AA 4.5:1 contrast and graphical marks at 3:1 contrast against the chart background. See docs/a11y-audit.md for the current audit notes.

Performance

Most dashboard-sized charts render smoothly with typical product datasets. For larger line-like datasets, LineChart, ComboChart, and Sparkline accept an opt-in downsample prop that uses LTTB to preserve the visual shape while rendering fewer points.

<LineChart
  title="Daily PMPM Trend"
  categories={categories} // 10,000 labels
  series={series} // one or more 10,000-point series
  downsample={1000} // render at most 1,000 points per line series
/>

Recommended values are usually 2x to 4x the chart's pixel width. For example, an 800px-wide chart generally looks good with downsample={1500} to downsample={3000}. Lower values can be useful for dense dashboards, but may remove subtle local movement.

Downsampling is off by default. When downsample is omitted, charts render the original data. When the data already has fewer points than the requested limit, the original array is passed through unchanged. Hover cards and keyboard navigation continue to use the original full dataset; downsampling only affects rendered line geometry.

LTTB expects data sorted by x ascending. The built-in chart integrations use the array index as x, so the current chart API is already sorted. If you use the utility directly with custom { x, y } points, sort first. LTTB preserves visual shape; it is not a statistical aggregation method for means, medians, or percentiles.

You can also use the utility upstream:

import { downsampleLttb } from '@atulya_26/charting-library';

const compact = downsampleLttb(rawPoints, 1000);

Chart States

Use chart states when data is loading, unavailable, or failed:

import { ChartLoadingSkeleton, ChartStateCard } from '@atulya_26/charting-library';

export function LoadingRevenueChart() {
  return <ChartLoadingSkeleton chartType="bar" title="Revenue" animate />;
}

export function EmptyRevenueChart() {
  return (
    <ChartStateCard
      variant="empty"
      title="Revenue"
      headline="No revenue data yet"
      description="Try a different time range or adjust your filters."
    />
  );
}

Supported loading skeleton types:

'bar' |
  'combo' |
  'line' |
  'donut' |
  'half-donut' |
  'histogram' |
  'sparkline' |
  'pointer-scale' |
  'map-bubble' |
  'sankey';

Local Development

The source code is available on GitHub:

https://github.com/Atulya26/ChartingLibrary

If you are viewing this package from npm and want to contribute, open an issue or pull request in the GitHub repository:

• GitHub repository: Atulya26/ChartingLibrary
• npm package: @atulya_26/charting-library

Install dependencies:

npm install

Run Storybook:

npm run storybook

Storybook runs on:

http://localhost:6006

Build the package:

npm run build

Build Storybook:

npm run build-storybook

Serve a static Storybook build:

python3 -m http.server 6030 -d storybook-static

Then open:

http://localhost:6030

Public API

The 1.0.0 package root intentionally exports chart components, shared chart chrome, chart primitives, public data types, token helpers, Sankey layout helpers, and the downsampleLttb utility. The full inventory is documented in docs/api-inventory.md.

Avoid importing private source files such as src/utils/*, src/stories/*, or src/chartUtils.tsx. If you need an internal helper promoted to public API, open an issue with the use case.

chartTokens is public and read-only for 1.0.0. It is useful for matching custom chart colors to the default visual language, but mutating it at runtime is not a supported theming API.

Sankey layout output is deterministic for a given input, but exact node coordinates and ribbon routing are not part of the semver contract. This keeps room for future layout-quality improvements without requiring a major version.

Quality Gates

Pull requests are expected to pass typecheck, lint, formatting, package build, Storybook build, and package size checks. Visual changes should be reviewed in Chromatic once the project token and baseline are configured.

Contributing

See CONTRIBUTING.md for local setup, validation commands, visual review expectations, and release workflow notes.

Package Usage Notes

• Import @atulya_26/charting-library/styles.css once per app.
• The library uses @innovaccer/design-system CSS internally and imports it from the package entry.
• React and React DOM are peer dependencies. 1.0.0 supports React 18.
• Map charts use d3-geo, topojson-client, and us-atlas.
• Published package output lives in dist/.
• Consumer installs support Node >=18.0.0. Local library development uses the Node version in .nvmrc.

Versioning

This package follows Semantic Versioning from 1.0.0 onward:

• Major releases may include breaking API changes and will include migration notes.
• Minor releases add features without breaking the stable public API.
• Patch releases include compatible fixes and documentation updates.

See MIGRATION.md for migration notes and policy details.

Release Flow

For maintainers:

git pull origin main
npm run build
npm run size
npm publish --access public --provenance

Prefer the repository's manual release workflow for official publishes so package build, size, and provenance checks run in a clean environment.

Links

• GitHub: Atulya26/ChartingLibrary
• npm: @atulya_26/charting-library
• Live Storybook: atulya26.github.io/ChartingLibrary
• Contributions: open an issue or pull request